Using the CloudBees CD/RO RESTful API

3 minute readReferenceDeveloper productivity

The CloudBees CD/RO REST API is an alternative to the Perl and Groovy APIs and is suitable to use in web applications. It has predictable, resource-oriented URL endpoints, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

The following HTTP methods are provided by the CloudBees CD/RO REST API:

  • POST—Create an object.

  • DELETE—Delete an object.

  • GET—Get an object.

  • PUT—Update or perform an action on an object.

Use the CloudBees CD/RO Swagger UI to visualize and interact with the REST API. In addition, the Swagger UI provides visual, inline documentation for every parameter of every resource—quickly find and work with CloudBees CD/RO resources and endpoints.

Considerations when accessing the CloudBees CD/RO REST API with the Swagger UI:

  • For most APIs, you enter information in the parameter fields; required parameters are clearly marked.

  • Batch API is not supported.

  • PUT operations:

    The CloudBees CD/RO REST API uses the PUT operation to update a specific object. In a PUT API call, you specify the values that you want to change. The response payload includes only those values that have changed rather than the entire object.

  • GET operations:

    The CloudBees CD/RO REST API uses the GET operation to get basic information about an object. For example:

    • To get all project objects, use this endpoint:

      https://<cloudbees-cd-server_hostname>/rest/v1.0/projects
    • To get a specific project object, use this form:

      https://<cloudbees-cd-server_hostname>/rest/v1.0/projects/myPlayground
    • If the API has a fully qualified property, put an extra slash in the URL:

      https://<cloudbees-cd-server_hostname>/rest/v1.0/server//foo

Accessing the REST API

All CloudBees CD/RO REST API endpoints start with this path component:

https://<cloudbees-cd-server_hostname>/rest/v1.0/

where <cloudbees-cd-server_hostname> is the host name or IP address of the CloudBees CD/RO server.

The CloudBees CD/RO REST API Swagger UI provides a complete reference to all endpoints. See Accessing the Swagger UI for more information.

URI Encoding

The contextual elements in an endpoint must be URI-encoded. Typically, parameters with a path or URL value require URI-encoding. Consider the POST operation for this endpoint:

/projects/{projectName}/pipelines

To access this endpoint with the value of Online Banking for {projectName}, use URI-encoding:

curl -X POST "https://<cloudbees-cd-server_hostname>/rest/v1.0/projects/Online%20Banking/pipelines? pipelineName=pipeline1" -H "accept: application/json" -d "{}"

Accessing the Swagger UI

Use the CloudBees CD/RO Swagger UI to visualize and interact with the CloudBees CD/RO REST API’s resources. This UI provides a convenient way for you to model API endpoints for subsequent use in web applications or in API development environments such as Postman.

The Swagger UI for the CloudBees CD/RO REST API is available via https://<cloudbees-cd-server_hostname>/rest/doc/v1.0

where <cloudbees-cd-server_hostname> is the host name or IP address of the CloudBees CD/RO server.

The Swagger UI lists all available API resources. From here:

  1. Click on the resource name to get a list of its available operations. Here, the operations for the tierMap endpoint are listed.

    rest api example1

    The operations for the resource appear below it.

  2. Click an operation name, such as POST. The operation expands to show the endpoint’s parameters in read-only mode.

  3. Click Try it out and enter the appropriate parameter values for the request. Required parameters are so noted.

    rest api example3
    To enter a parameter of type filter click its Add item button and specify the filter as a JSON formatted string. For information about constructing a filter see the findObjects command.

  4. Click Execute to invoke the endpoint. The response returns. The response includes the following information:

    • Curl —The cURL-formatted request suitable to use on a command line prompt.

    • Request URL –The request URL suitable to use in a browser.

    • Response Body –Response in a standard format with the application level status, the results, and any errors. This is also referred to as the Response Payload .

    • Response Headers –Information about the response format.

    • Response Code –Status of the response at the protocol level.