This guide describes interactions with Jaws Deploy platform programmatically via its RESTful API.

The API is focused on creating, deploying and promoting releases. More API endpoints related to topology management are coming soon.

Base URL

When issuing a request append the specific request endpoint to this base URL:

https://app.jawsdeploy.net/api

Authentication

All endpoints are protected with Basic Authentication. In order to authenticate against the API you'll need a Service Account and an API Key:

• Go to Settings / Service Accounts
• Create a service account and specify access rights using roles.
• Create an API key for this account and store the key securely in a key-vault or a password manager.

Read more about the above procedure here: Service Accounts and automation.

When issuing an HTTP request attach the following request header:

Authorization: Basic <credentials>

‍where <credentials> is a string created by base-64 encoding the login (Service Account ID) and an API key associated with this Service Account. Combine both values delimited by a single colon character. Pseudo-code:

request.Headers["Authorization"] =
    "Basic " +
    Base64_Encode("{serviceAccountId}:{apiKey}");

‍In case the credentials header is missing or is incorrect, the following response will be returned:‍


401 Unauthorized
{
   "error": "invalid credentials",
   "errorcode": 2002,
   "requestid": null
}

‍More information on creating the <credentials> token:
‍RFC 7617 - The 'Basic' HTTP Authentication Scheme (ietf.org)
‍HTTP authentication - HTTP | MDN (mozilla.org)

Requests and responses

POST, PUT and DELETE requests accept JSON-encoded bodies. Use the following request header when issuing these type of requests:

Content-Type: application/json

GET requests accept parameters in the query string.

The API responds with JSON-encoded bodies and standard HTTP status codes:

• 200 OK when the request was successfully processed.
• 400 Bad request when the request body is missing, when it is invalid (e.g. does not include required parameters) or when JSON content is malformed.
• 401 Unauthorized when authentication fails (e.g. incorrect API key was used, or the API key did not have sufficient access rights).
• 415 Unsupported Media Type when the Content-Type header was incorrect for endpoints that expect JSON payload (POST, PUT and DELETE).

Error codes

UnknownError = 1001
InvalidAccessToken = 2001
InvalidCredentials = 2002
InsufficientPermissions = 2003
InvalidParameter = 3001