All service applications must publish OpenAPI specifications of their external APIs. While this is optional for internal APIs, i.e. APIs marked with the component-internal API audience group, we still recommend to do so to profit from the API management infrastructure.
An API is published by copying its OpenAPI specification into the reserved
/zalando-apis directory of the deployment artifact used to deploy the
provisioning service. The directory must only contain self-contained YAML
files that each describe one API (exception see [234]). We prefer this
deployment artifact-based method over the past (now legacy)
.well-known/schema-discovery service endpoint-based publishing process, that
we only support for backward compatibility reasons.
Background: In our dynamic and complex service infrastructure, it is important to provide API client developers a central place with online access to the API specifications of all running applications. As a part of the infrastructure, the API publishing process is used to detect API specifications. The findings are published in the API Portal - the universal hub for all Zalando APIs.
Note: To publish an API, it is still necessary to deploy the artifact successful, as we focus the discovery experience on APIs supported by running services.
Owners of APIs used in production should monitor API service to get information about its using clients. This information, for instance, is useful to identify potential review partner for API changes.
Hint: A preferred way of client detection implementation is by logging of the client-id retrieved from the OAuth token.