Access API definitions

When xDI Runtime exposes a delivery as a web service, the web service is described in automatically generated definition files. The definitions automatically update when web services are exposed or updated.

Definitions are available in OpenAPI and in Swagger formats. You can view web service definitions from a dedicated URL, in JSON format. The runtime also bundles a visual interface for the definitions, Swagger-UI, which has its own URL.

All URLs are listed on the runtime console at startup, and printed in the xdi-runtime.log file in the runtime log directory.

OpenAPI definition

The OpenAPI definition URL ends with ?openapi3.json.

Example 1. Example URL for OpenAPI

HTTP Rest v3 - Definition (local url): http://localhost:42200/rest/DeliveryService/3/default?openapi3.json

After you open the URL, your web browser needs runtime credentials to continue. Enter the runtime username and password to view the OpenAPI definition in JSON format.

Swagger definition

The Swagger definition URL ends with ?swagger2.json.

Example 2. Example URL for Swagger

HTTP Rest v3 - Definition (local url): http://localhost:42200/rest/DeliveryService/3/default?swagger2.json

After you open the URL, your web browser needs runtime credentials to continue. Enter the runtime username and password to view the Swagger definition in JSON format.

Visual API interface

The Swagger-UI tool, to view and work with your web service in a visual format, ends with ?swagger-ui.

Example 3. Example URL for Swagger

HTTP Rest v3 - UI (local url): http://localhost:42200/rest/DeliveryService/3/default?swagger-ui

After you open the URL, your web browser needs runtime credentials to continue. Enter the runtime username and password to open the Swagger-UI tool.

From this tool, you can view the web service endpoints, and test them with data.