REST API

Fetch data and automate your workflows with the Continuous Delivery for Puppet Enterprise (PE) REST API. Use the API to promote pipelines based on your own criteria and automate workspace setup to make onboarding new users more streamlined.

The Continuous Delivery for PE REST API uses the OpenAPI standard to define and document the API via a specification. The OpenAPI Initiative has extensive documentation of the standard which can be followed. Continuous Delivery for PE uses version 3.0.1 of the standard.

If you are familiar with REST and OpenAPI, skip to the OpenAPI specification section for more specific details on how Continuous Delivery for PE implements OpenAPI.

Authenticate public APIs

The Continuous Delivery for Puppet Enterprise (PE) API supports authentication via personal access tokens associated with Continuous Delivery for PE accounts. Authentication tokens are tied to the permissions granted to the user through role-based access control (RBAC), and they provide the user with the appropriate access to application programming interfaces (APIs).

Before you begin
You need the personal access token you created in Add a personal access token. It is required for authentication.

Using personal access token to authenticate the Continuous Delivery for PE public API.

Add the personal access token you copied when creating the token and add this to the Authorization header of the API call. For example: 
curl --insecure --header \ 
 "Authorization: <token value>" \ 
 "https://<hostname>/cd4pe/api/v1/user"

REST API tutorial

Learn how to navigate a Continuous Delivery for Puppet Enterprise (PE) workflow entirely through the API using curl and bash.

Before you begin

Make sure that you have read the Authentication section and have a personal access token. You need the personal access token you created in Add a personal access token. It is required for authentication.

This tutorial guides you through a Continuous Delivery for PE workflow using the API.

  1. Create a workspace. From the command line run: 
    curl --insecure --header “Authorization: <token value>” --request POST “https://<hostname>/cd4pe/api/v1/workspaces” --data ‘{ “name”: “my_workspace” }’
    This returns: { “domain”: “d3”, “name”: “my_workspace” }

    The application returns a 200 HTTP status code along with a JSON response body which contains the created workspace information. To perform subsequent API calls you need to extract the workspace ID from the response (referred to as the domain in the v1 create workspaces endpoint).

    Any authenticated user can create workspaces in Continuous Delivery for PE, which means that no RBAC privileges are required for this step.

  2. Use the API to integrate a VCS provider in the workspace. This allows you to create code projects from the VCS provider. For example, connect a GitLab instance to the workspace: 
    curl --insecure --header “Authorization: <token value>” --request POST “https://<hostname>/cd4pe/api/v1/vcs/gitlab?workspaceId=d3” --data ‘{ “token”: “<gitlab_token>”, “host”: “https://mygitlab.example.net”,  “caCertificate”: “<ca_cert_data>” , httpClone: true  }’
    This returns: { “id”: “<uuid>”, “host”: “https://mygitlab.example.net”, httpClone: true }
    Note: The workspace ID is used in the query parameter of the request. Many entities in the application exist within a workspace, the workspace ID identifies which workspace to create the Gitlab integration in.
What to do next
Once the VCS provider is integrated, you can use the API to create code projects and pipelines within those projects. See the next section on the OpenAPI specification for more information about the OpenAPI specification file as much of the API documentation is within this file.

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.