API documentation and groups

Actualog API documentation is generated from the server API metadata and the DTO contracts used by the endpoints. The documentation pages are not written by hand.

Use:

What a tag means

In OpenAPI, a tag is a navigation label attached to an operation. RapiDoc uses tags to build the operation list in the left navigation.

Actualog generates each operation tag as:

Top-level group / API section

For example:

Products / Product
Products / Product Mass Update
Data Integration / Company Feed
Taxonomy / Attribute

A tag is not a permission rule, not a company role, and not a database ownership boundary. It is a documentation navigation label.

Where groups come from

Actualog adds the OpenAPI extension x-tagGroups so the viewer can show tags under clear top-level groups. These groups are generated by the OpenAPI document generator from controller/action metadata:

  • ApiAudience.Public decides whether an endpoint appears in /docs/public.
  • ApiClassificationAttribute marks the endpoint as Business Integration, Platform/Admin, Security/Account, Internal UI Support, or System Runtime.
  • Controller names and route meaning place business endpoints into groups such as Products, Data Integration, Taxonomy, Workspace, Collaboration, Reference Data, or Search & Content.
  • Explicit operation metadata or XML comments provide the short title and detailed description.

The Public API is the business integration contract for Actualog workspace data and workflows. It includes endpoints that are useful to integration clients for product data, reference data, taxonomy, data integration, workspace objects, collaboration workflows, and search/content operations.

Public docs versus all docs

/docs/public includes only endpoints marked as public and callable by company API credentials, subject to the credential owner's permissions and plan entitlements.

/docs/all includes the full technical inventory for administrators. It also shows Platform/Admin, Security/Account, Internal UI Support, and System Runtime endpoints. Public API credentials do not grant access to those internal or administrator operations.

Sorting rules

The documentation sorts navigation for scanning:

  • Authentication appears first when the viewer shows it.
  • Business integration groups are sorted alphabetically.
  • Platform/Admin, Security/Account, Internal UI Support, and System Runtime groups follow after business groups and are also sorted alphabetically.
  • Product core, Product Overview, Product Mass Update, product identifiers, media, variants, quality, review, publish, and related product workflows all stay under Products. They are separate API sections inside the same top-level product group.

Components and schemas

OpenAPI components describe reusable request and response schemas. In Actualog these schemas must be DTO or scalar contracts. Persistence model types from Actualog.Data.* are rejected during generation.

Actualog adds x-componentGroups so component schemas can be browsed by the same business/admin grouping as operations. When a schema is used by multiple endpoint groups, the generator chooses the group with the strongest usage and falls back to stable schema-name rules for shared schemas.

How to document a new endpoint

When adding or changing an API endpoint:

  1. Keep the route stable unless a route change is explicitly approved.
  2. Use DTO/scalar request and response contracts.
  3. Set ApiAudience.Public only when the endpoint is a supported business integration contract.
  4. Set ApiClassificationAttribute so /docs/all can separate business, platform/admin, security/account, internal UI, and runtime operations.
  5. Add OpenApiOperationInfoAttribute with a short action-like summary and a fuller description.
  6. Put long behavior notes, permissions, compatibility details, and plan restrictions in the description, not in the short summary.
  7. Regenerate public.json and all.json, then check that navigation titles are short and that components are grouped correctly.

RapiDoc is the API operation list and endpoint-detail viewer. The Actualog DTO component browser below it provides grouped search for request and response component schemas only. Clearing the DTO search box restores all component groups.