Skip to content

OpenAPI

The WebAPI publishes an OpenAPI 3.0 description of every endpoint defined under Setup, derived from the endpoints and the integrations behind them, so a caller can read what each route accepts and returns without a copy of the design.

Where it is

Two URLs under the WebAPI's application path, both anonymous:

  • http://<server>/IManWebAPI/openapi/schema is the description itself, as JSON. It is served with Access-Control-Allow-Origin: *, so a browser-based tool on another host can load it.
  • http://<server>/IManWebAPI/openapi/webapi.html renders it: one operation per endpoint, with its request and response schemas. The page loads its viewer, RapiDoc, and its syntax highlighting from public CDNs, so the browser that opens it needs internet access. The description does not.

The rendered OpenAPI page: a dark navigation bar listing the operations by method and route, and the WebAPI Sage300 Order Post operation open, showing POST sage300order, its request body schema of customer, orderNumber and lineItems, and its 200 response schema

How the description is built

Every endpoint under Setup becomes one path and one operation:

  • the path is the endpoint's Route exactly as typed, tokens and query string included, and its description is the endpoint's Description;
  • the operation is the endpoint's HTTP Method, its operation id is <Method>-<Endpoint ID>, and its summary is the integration's Comment;
  • the response code is the endpoint's Result Status Code;
  • an endpoint that does not allow anonymous requests declares HTTP Basic as its security scheme.

The endpoint's integration supplies the schemas:

  • the request body schema comes from the first JSON Reader whose Source is Transaction, walking down the first branch from the WebAPI Reader;
  • the response schema comes from the first JSON Writer whose Target is WebAPI, found the same way.

Each schema is that reader's or writer's transactions and fields, so what the description promises matches what the integration reads and writes. A GET has no request body. An endpoint with no integration, or an integration with no such reader or writer on its first branch, is listed with its route and method and no schema.

Only JSON is described. An endpoint whose body is XML, a posted form or a file is listed without a schema, and the route's parameters are not listed as OpenAPI parameters; they are visible in the path itself.