Skip to main content

OpenAPI

We publish OpenAPI 3-compliant spec files for the Sales Channel Services API. These specification files describe the API interface we expose in a machine-readable format. This includes information like the available authentication mechanisms, a list of the endpoints we expose, the arguments those endpoints expect and the shape of the possible responses.

Types of Specs​

We publish two types of specification files:

  • Generic specification files, which are environment-agnostic.
  • Environment-specific specification files, which come baked-in with environment specific configuration.

Generic​

You will find a generic OpenAPI specification file for the latest version of the API as part of this documentation website. It can be viewed and downloaded from the OpenAPI Spec page.

This specification will have placeholders for certain environment specific values. Currently, there are two places where to expect divergences:

  • The server hostname will render with a placeholder domain https://{hostname}.
  • The OAuth2 authentication method has various placeholders to point it to the correct Azure AD B2C instance. Variables include {tenantName} and {userFlow} in the authorization URL, and {applicationUri} and {scope} to build up the required scope.
info

These specification files are primarily presented for showing humans the API interface we expose. If you need a populated version of the spec, then obtain an Environment Specific specification file, which will not include any placeholders.

Environment-Specific​

At runtime, the application can provision a fully populated OpenAPI spec. It will be hosted in JSON format under /api-json of the hostname of each environment.

Example

For the production server endpoint https://scs.api.puro.earth, you can find the OpenAPI spec at https://scs.api.puro.earth/api-json.

OpenAPI UI​

You can also consume the environment-specific OpenAPI specs through the OpenAPI UI. It will be published at /api of the hostname of each environment.

The OpenAPI UI lets you interact with the API in a fully pre-configured environment. This includes a working OAuth2 flow, which allows making requests against the API in that environment without having to leave the GUI.

Example

For the production server endpoint https://scs.api.puro.earth, you can find the OpenAPI UI at https://scs.api.puro.earth/api.