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
Listed below are the resources exposed via the REST API that can be created, modified, or deleted.
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 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 returned from API endpoints will be JSON encoded payloads. Detailed below are the different types of errors that can occur,
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
.
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": "..."
}