OpenAPI administration

The API portal runs as its own process and serves each caller a document filtered to the channels that the caller's credentials can invoke - your API consumers get live, accurate documentation without you writing or publishing anything. For the consumer side - signing in, browsing and try-it - share Using the API portal with them.

The portal shows the Zato logo on its sign-in page and in its header. Two environment variables of the portal process replace it:

When both are set, the image file is used. When neither is set, the portal shows the Zato logo.

Two more files, placed in /opt/hot-deploy/api-portal/branding/, change the rest of the look:

The directory itself can be changed with the Zato_API_Portal_Branding_Dir environment variable.

Architecture

The portal is a separate process on its own port, firewalled independently of the servers. Browsers only ever reach the portal - it communicates with the servers over Redis Streams, and no server port is exposed to API consumers. The OpenAPI document itself is built and filtered on the servers: the full document never leaves them, the portal receives only the already-filtered version for the signed-in caller and renders it.

The document is rebuilt on the servers when the deployed services or REST channels change - on hot-deploy and on channel create, edit and delete events - and cached in memory, so per-request work is only the per-caller filtering.

The portal listens on port 8185 for plain connections and 8186 for SSL, changeable through Zato_Port_API_Portal and Zato_Port_API_Portal_SSL. Certificates and SSL options follow the same environment variables as the rest of the platform - see SSL/TLS configuration.

Channel eligibility

A REST channel appears in the OpenAPI document only when it meets all five conditions:

1. It is a REST channel - connection channel, transport plain_http
2. It is active
3. It is not internal
4. It points at a service deployed on the server
5. Its OpenAPI flag is not off - an unset flag means included

The same rules bind everyone, admins included. Inactive channels, internal channels and channels with the flag off are in nobody's document, and the try-it relay refuses them for everyone.

Only REST channels are documented, never bare services - a deployed service with no channel pointing at it appears in no document.

The document describes each endpoint by its URL path, its HTTP method, its input and output, and the docstring of its service - the first sentence of the docstring is the summary and the whole docstring is the description. Endpoints are grouped by the first segment of their URL paths that names a resource, and a section of more than eight endpoints is divided by the resource that follows it, so /api/healthcare/patients/{patient_id} belongs to the Healthcare / Patients group when Healthcare is a large section and to the Healthcare group otherwise. The segments that name no resource are left out of the group names:

1. Version segments, such as v1 or 2.0.
2. The names of the roles of the modules in a project, such as api, channel, channels, adapter or core.
3. Opaque identifiers, such as the hexadecimal IDs some systems put in their URL paths.
4. Actions, such as create, get-list or update, which describe what an endpoint does with a resource rather than the resource itself.

A segment with dots in it, such as billing.invoices, is read as one segment per part, and a resource whose name is split across two segments, such as /restricted/access, joins the group of the same resource written as one, /restricted-access. An endpoint whose path names no resource after its section joins the group of another endpoint with the same opaque identifier, if there is one, and the section's General group otherwise. The names of the services behind the endpoints never appear in the document.

Headers added in the portal's Options are passed to the service, which reads them from self.request.http.headers as it does for any REST request.

Every REST channel has an "OpenAPI" checkbox in its create and edit forms in the Dashboard, checked by default. Unchecking the box removes the channel from every document while the channel keeps serving traffic - uncheck it for endpoints that should work but not be advertised.

Per-caller filtering

Callers sign in to the portal with existing security definitions. The sign-in form has an auth type selector - with Basic Auth, callers enter the username and password of a Basic Auth definition or the client ID and secret of a Bearer token definition, with Bearer token, they enter a token that an active Bearer token definition accepts, static or JWT, verified as a REST channel verifies it, and with API Key, they enter the API key itself. No new credential type exists for the portal.

A caller's document contains only the channels that accept the caller's definition. A channel's own security definition, if it has one, has to be the caller's, and if the channel's security groups have members, one of them has to include the caller's definition too. A channel with no definition of its own and no group members accepts no definition and is in the documents of admins only. The try-it relay enforces the same rules - a channel outside a caller's document cannot be invoked through the portal either.

Admins sign in with the same credentials as the Dashboard admin and receive the unfiltered document - all the channels eligible per the rules above - with full try-it access.

Contract diffing

On every rebuild the server compares the new document against the previous one and logs the differences that break existing consumers - removed endpoints, removed fields and type changes. The report appears in the server log as part of the deploy output, one warning per change, prefixed with OpenAPI breaking change:. The report is informational - the deploy itself proceeds - but it makes a contract break visible at deployment time, before any consumer's calls start failing.

See also

Learn more