Overview¶

Djinn CI provides a REST API through which you can interact with the platform. The API accepts JSON encoded request bodies, and returns JSON encoded responses.

https://api.djinn-ci.com

Resources¶

Listed below are the resources exposed via the REST API that can be created, modified, or deleted.

Authentication¶

Authentication to the API is handled via a bearer token that is sent in the Authorization header on each request. This token can either be generated by the server itself, or generated as part of the OAuth authorization flow for an application.

For more details on the OAuth authorizatrion flow see Authorizing an OAuth app.

The amount of access a user has to the API is dictated by the scopes of the bearer token. For more information about token scopes, see Token scopes.

Pagination¶

Pagination of multiple resources is handled via the Link header in the response. The Link header will contain at most two links, one for the previous page under prev, and another for the next page under next, for example,

Link: <https://api.djinn-ci.com/builds?page=1>; rel="prev",
      <https://api.djinn-ci.com/builds?page=3>; rel="next"

Errors¶

Errors returned from API endpoints will be JSON encoded payloads. Detailed below are the different types of errors that can occur,

Validation errors¶

Validation errors occur when incorrect data is sent to an API endpoint. A JSON object will be returned, where each key in the object will be a field name, and its value will be an array of strings detailing the errors that occurred. For example assume we were to submit a build without a manifest then we would get the following error,

{
    "manifest": [
        "Build manifest is required",
        "Build manifest, invalid driver specified",
    ]
}

on validation errors, the HTTP status code will be that of 400 Bad Request.

Internal errors¶

Should an internal error occur from the side of the API then the below JSON object will be sent with an appropriate 5xx HTTP response code,

{
   "message": "..."
}

if debug mode for the server is enabled, then an additional stack parameter will be in the JSON object detailing the stack trace of the error, if it was a fatal error,

{
   "message": "...",
   "stack": "..."
}

Overview