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.

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.
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.