OpenAPI specification
Continuous Delivery includes
the OpenAPI specification and it can be fetched from the web server from the following
endpoint: curl --request GET
“https://<hostname>/cd4pe/api/openapi.yaml”
Continuous Delivery-specific metadata
While the OpenAPI specification adheres to a specific standard schema, it is very extensible and allows API authors to define metadata on any object in the API.
x-internal parameter is set to
true on API endpoints and operations to indicate that the
endpoint is an internal API meant to be used by the UI. Endpoints and operations
where this tag is set are not intended for customer use. The parameter is set either
on a path or specific HTTP verb, for endpoints where some operations are allowed but
not others. Please refer to the OpenAPI specification when learning how to use the API. The file is quite large and so it may be helpful to use one of the many available tools to visualize the specification.
Version and compatibility
All endpoints in the Continuous Delivery are versioned so that updates do not break existing workflows. When an endpoint is removed from the Continuous Delivery API, a deprecation warning is issued at least 2 minor releases before the endpoint is removed. The deprecated field in the OpenAPI specification indicates what operation or component is deprecated.
An API breaking change is any change to the API that would cause a caller to begin failing, such as:
- Removing an endpoint without giving a deprecation warning.
- Adding a new required field in a request body, query parameter, or response body.
- Removing a field from a request body, query parameter, or response body.
- Changing the type of a field in a request body, query parameter, or response body.
Changes that are not considered to be API breaking:
- Adding a new optional field in a request body, query parameter, or response body.
- Making a required field optional.
