This page contains the documentation on how to use devopness through API calls.

Note: This documentation is not complete, so for missing parts or inaccurate API description please reach out to the devopness API team on our GitHub open source repository.

devopness's API exposes all devopness features via a standardized programmatic interface. Through devopness API a registered Devopness user can perform every operation you can do on https://www.devopness.com web interfaces and mobile apps.

To start using the devopness API you will need an API Token. Go to the API Tokens section to learn about the different types of tokens and how to generate them.

The devopness API is based on HTTPS requests and JSON responses, organized around REST. Our API has predictable resource-oriented URLs, accepts requests with JSON-encoded bodies with arguments, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

All dates in the API use UTC and are strings in the ISO 8601 "combined date and time representation" format:

2015-05-12T15:50:38.000000Z

The devopness API uses standard HTTP status codes to indicate the success or failure of an API call. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error on the API servers and are very rare.

The body of the error response is a JSON in the following format:

{
  "message": "The given request data was invalid"
  "errors": { // Optional errors object, returned only when there are detailed error message to be shared
      "field_1": [
          "Optional error message related to field_1"
      ],
      "field_2": [
          "Optional error message related to field_2"
      ],
  }
}

Routes and Endpoints

A route is a URI which can be mapped to different HTTP methods. The mapping of an individual HTTP method to a route is known as an endpoint. devopness API exposes, as much as possible, well standardized endpoints with resources and segments leading the path to access the desired resource data.

Each resource mentioned in an endpoint segment has its name written in the plural form, as we are always referencing a collection of objects, that might or might not be filtered by a single ID or extra query string parameters.

Resources and nested resources endpoints

Basically there are two types of endpoints used in devopness API:

1. Resource endpoints:

Pattern:

/collection/{resource_id}/[{action}]

Examples:

2. Nested resources endpoints:

Nested resources are used when there is a clear hierarchy between the parent resource and the subresource, or for convenience, to make it easy and predictable to filter subresources belonging to a parent resource. In devopness API design we strive to avoid nesting resources more than 1 level deep + one action related to the child resource or to the relationship between parent and child.

Pattern:

/parent-collection/{parent_id}/{child-collection}/{child_id}/[{action}]

Examples:

When a request is successful, a response body will typically be sent back in the form of a JSON object. Exception to this rule is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body.

Response codes

Response codes indicate success or failure of request processing. Status codes from the 2xx range indicate that request has been accepted. If the returned code is from the 4xx or 5xx range then it reveals either problem with the request or inability to process data. See below for a list of HTTP Status codes used by devopness API:

Pagination

Requests that return multiple items are paginated by default. Specific pages can be requested setting the page parameter. When page parameter is not present, the first page will be returned. By default 20 items are returned per page. A custom page size up to 100 can be set with the per_page parameter.

Note: some endpoints ignore the per_page parameter, returning all results at once. e.g.: /static/* endpoints.

Example:

In the example above, we retrieve items of page 5 setting the size of 15 items per page.

Browsing paged results

The Link header in paged responses carry links to pages for navigation purpose. Devopness API adopts the RFC 8288 as the reference for our implementation of Link header contents.

Links to the first, next, previous and last pages are included such that API clients don't have to hardcode or construct any links. The page links that may be present in the Link response header are listed below:

Optional links are not present if the currently requested page has no relative links to point to:

• Lack of a previous link in the response indicates the beginning of the collection
• Lack of a next link in the response indicates the end of the collection

TO DO: define the rules for object expansion and document it here

API Tokens are the authentication method used by the devopness API.

Every request must include a valid token in the Authorization header:

Authorization: Bearer <your_api_token>

There are two types of tokens available:

• API Token (project scoped): restricted to resources of a specific project, with permissions defined by the role assigned to the token. See Projects - API Tokens

• Personal Access Token (PAT): inherits the permissions of the user who created it. See Users - Personal Access Tokens

More information about API Tokens can be found in the API Tokens - Devopness Docs

API Tokens (project scoped) provide restricted access to resources within a specific project. Permissions are defined by the role assigned to the token, making them ideal for automation's, scripts, or integrations that should not access resources outside the project.

Include the token in all project-related requests using the Authorization header:

Authorization: Bearer <your_api_token>

For instructions on creating and managing project tokens, refer to the API Token (project) - Devopness Docs

Personal Access Tokens (PATs) inherit all permissions of the user who created them. They allow performing any action that the user is authorized to do across all projects accessible by the account.

Include the PAT in all API requests using the Authorization header:

Authorization: Bearer <your_api_token>

For instructions on creating and managing PATs, refer to the Personal Access Tokens - Devopness Docs

Client API applications might need to retrieve possible accepted values to fulfill their forms and allow end users to pick values from a list of valid data. All static data that need to be used through devopness API client applications is provided through the /static/* endpoints.