OpenAPI specification

Continuous Delivery for Puppet Enterprise (PE) 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 for PE-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.

Note: The x-internal parameter is set to true on API operations to indicate that the endpoint is an internal API meant to be used by the UI. This tag is 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. For more information on this tag and others, please refer to the tags array documentation.

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 for PE are versioned so that updates do not break existing workflows. When an endpoint is removed from the Continuous Delivery for PE 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.