CDA REST API - General Info

As an Application Developer or Administrator, you can use the REST API to communicate with the CDA system.

Overview

A REST API allows you to make requests for resources on a web server which, in turn, returns responses containing the requested information. Calls to REST API endpoints can be made with almost any programming language.

Unlike SOAP, REST APIs use HTTP as the transport protocol (although both server and client can be based in any language). Furthermore, a REST API does not follow a standard message format, the message specifications are only to be found in the corresponding documentation.

Do you want to execute workflows? Simply send a POST request to http(s)://myCDAServer/cda/api/data/v1/executions. Get the Package with ID 6784? Send a GET request to http(s)://myCDAServer/cda/api/data/v1/packages/6784. The CDA REST API allows this and much more!

CDAREST API architecture

What can I do via REST API?

The CDA REST API allows you to:

• Create, update and delete CDA objects and their dependencies including handling of custom and dynamic properties.
• Show paged list of CDA objects and allow searching and filtering.
• Start CDA workflows.
• Get the status of workflow executions.
• Work with the CDA entities as code.
• Display performance data.

Scenarios

CDA REST API enables you to perform operations such as:

• triggering your deployment workflows via Jenkins
• approving application deployments via HipChat

General Patterns of the CDA REST API

• Base URL - The API is accessible via a sub-domain: http://<CDAServer>/cda/api/data/v1
• Encryption - It is recommended to use https to access the CDA API.
• API response - The API returns JSON files even if it is accessed via the browser. This eases the development process, especially in case of debugging.
• Versioning - Versions are encoded in the URL.
• Instance references - Instances are always referenced by their type and either by their name or unique id.
• HTTP method mapping - The following HTTP methods are used (for more info see Methods):
  • GET
  • POST
  • DELETE
• Dates - Dates are always returned in UTC format.
• Endpoints - Every entity has an endpoint. Dynamic properties are embedded and do not have a separate endpoint.
• Query parameters - Any resource parameter can be used for querying by specifying it in the request URL. For more information see Common Request and Response Parameters.

• Pagination - Collections are returned in pages by default. Clients can request records by specifying a start index and a page size. For more information see Pagination.

URI Format

The REST API URIs have the following structure:

https://{hostname}/{application}/api/{api_name}/{version}/{resource}.{format}

Example:

https://AWI.mycompany.com/api/callbacks/v1/myresource.json

• https://

  HTTPS access to the API.

• hostname

  Hostname of the API application.

• application

  Web application hosting the API.

• api

  Fixed name after the root path of the web application in order to avoid conflicts with application routes.

• api_name

  An application may provide special purpose APIs to simplify development with the API. E.g: deployment.

• version

  Version of the API.

• resource

  The resource you make the request on.

• format

  Serialization format of the API. Currently only JSON is supported.

Common Request and Response Parameters

Request parameters

You can add query parameters to the URIs to filter the response output.

Name	Value	Description
start_at	integer	Filters by page number of the response to be displayed. For more information see: Pagination
max_results	integer	Sets a maximum number of results to be displayed per page (=pagesize). For more information see: Pagination

Important! An error message will be displayed if an unexpected query parameter is submitted.

Response parameters

• hasmore
• total
• data
• id
• name
• archived
• status
• version
• connection_url
• connection_port

Note: Values of protected properties (both custom and dynamic) will never be exported, the properties will be contained in the response with null value. Null values for protected properties will be ignored in update operations, the original values remain unchanged. Nevertheless, setting an empty string like "password": "" will reset the value to an empty value.

Collection resources

If a resource is a collection of entities, the response shows the total number of entities:

Example:

GET / applications/98454/ components

total: in this example, the Application with ID 98454 has 3 components (total= total number of resources in the collection).

hasmore: indicates if the response contains all data in the collection. Possible values:

• true = the collection contains data which is not included in the collection.
• false = you have reached the last page.

data: objects contained in the collection.

Methods

The following methods are used for resources:

Verb	Action
GET	Used to get a list of resources or a single one. No data is changed with this operation. GET / applications (list of resources) GET / applications / ID (single resource) Example: curl -D- -u <client>/<username>/<department>:<password> -X GET -H "Content-Type: application/json" http://<host>:<port>/cda/api/data/v1/applications
POST	Used to add a resource or to modify an existing one. POST / packages (to add a new resource) POST / package / ID (to update an existing resource) Example: curl -D- -u 100/AUTOMIC/AUTOMIC:automic -X POST -H "Content-Type: application/json" http://<host>:<port>/cda/api/data/v1/packages -d '{"name": "11.22.33", "folder": "CR08", "owner": "100/AUTOMIC/AUTOMIC", "custom_type": "Deployment", "application": "DemoApp"}' Note: Resources can only be added or updated by one.
DELETE	Used to delete single resources. Example: DELETE / packages / ID DELETE /applications -> not allowed

Important! Other HTTP methods such as PATCH, PUT or HEAD are not used.

Note: Leading and trailing spaces in the API input will be trimmed.

Authentication

The REST API requires basic authentication. In order to send requests, you must enter the same credentials as to connect to an AE system on your GUI client. The client, user, department, and password information must be part of the HTTP(S) header: (CLIENT/USERNAME/DEPARTMENT) + Password. The Automation Engine decides whether a REST request in the user context is allowed or not and responses accordingly.

The CDA REST API does not support password encryption for the password that is stated in the REST request. It is recommended to use HTTPS to secure the transmission of this information.

Pagination

In CDA REST API, responses are paginated to make results easy to handle.

Pagination can be very useful when you make a request to the CDA REST API and receive a lot of results. For example, if you send a request to get all existing components, thousands of records may be retrieved.

How to set limit parameters

CDA REST API allows you to set the following limit parameters:

• start_at: Page number of the response to be displayed. (Default value is 0)

• max_results: Maximum number of results per page. (Default value is 20)

  The default value can be configured in the customer.config file (Automic\Release.Manager\WebUI\customer.config) by adding the following key:

  <add key="REST.DefaultPageSize" value="20" />.

  The parameter "total" helps to determine how many pages the result would have.

Note: If "start_at" or "max_results" are not set, default values will be used.

How do I know that I am on the last page?

You can see that you have reached the last page when the value of the hasmore field in the response is "false".

Filtering

You can apply filters to narrow the number of records returned.

GET requests can be filtered by the filter operator "=" (equals).

For example: GET /packages?name=cda

See also:

• REST API Reference
• AE REST API - General Info
• Analytics REST API - General Info
• Analytics REST API Key Management
• Response Definitions