Use 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

Access the REST API

All CloudBees CD/RO REST API endpoints start with this path component, where https://<cloudbees-cd-server_hostname>/rest/v1.0/, and 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. Refer to Access the Swagger UI for more information.

Access the REST API using curl commands

To use curl commands to protected API routes that require authorization, a sessonId is required.

To access the REST API using curl commands:

Use ectool to sign in. To sign in and specify the CloudBees CD/RO server hostname, username, and password, the syntax is:

ectool --server serverName login "username" "password"

For example:

ectool --server bldg1server login "Ellen Ernst" "ee123"
If your password is not as part of the login command, you are prompted to provide it.

If successful, it should return an output similar to the following:

<response requestId="someId" nodeId="someIp">
    <sessionId>SOMESESSIONID</sessionId>
    <userName>Ellen Ernst</userName>
</response>

Now, any curl requests that are sent to protected routes should have this sessionId included as a cookie. For example:

curl -k -X GET "bldg1server/rest/v1.0/projects" -H "accept: application/json" --cookie "sessionId:SOMESESSIONID"

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 "{}"

Access the Swagger UI

Use the CloudBees CD/RO Swagger UI to visualize and interact with the CloudBees CD/RO REST APIs 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. Select the resource name to get a list of its available operations. Here, the operations for the tierMap endpoint are listed.

    Tier map endpoints
    Figure 1. Tier map endpoints

    The operations for the resource appear below it.

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

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

    Parameter values
    Figure 2. Enter parameter values
    To enter a parameter of type filter select Add item and specify the filter as a JSON formatted string. For information about constructing a filter, refer to the findObjects command.
    Filter parameter
    Figure 3. Swagger filters
  4. Select 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.