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:

• 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.

When issuing an HTTP request attach the following request header:

Authorization: Basic <credentials>

‍where <credentials> is a string created by base-64 encoding login and API key delimited by a single colon. Pseudo-code:

request.Headers["Authorization"] =
    "Basic " +
    Base64_Encode("{login}:{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

Release - Create

This API endpoint creates a new release of a specific project. Release is an entity that represents state of the project (including a snapshot of all variable values and step logic). This endpoint does not trigger a deployment. Response includes releaseId which can be used to execute a deployment.

Release - Deploy

This API endpoint deploys an existing release to specified environments or using specific lifecycle phase. After successful execution the response will include a list of deployment IDs which you can later use to check the deployments status.

Release - Promote

This API endpoint deploys a specific release version of a given project to specified environments or using specific lifecycle phase. If no release version is provided then Jaws Deploy will pick an existing release with the highest version number (according to SemVer 2.0 rules). In such case the specified project needs to have at least one release. Otherwise an error will occur.

This endpoint is especially useful in CI/CD scenarios, where the build server does not track Jaws Deploy release identifiers. In such case it is enough to provide only project ID and the environment name to promote the latest release.

Similar to Release - Deploy response contains unique identifier of the created deployment entity.

Release version comparison and sorting is based on SemVer 2.0. More information: Semantic Versioning 2.0.0 | Semantic Versioning (semver.org)

Deployment - Get status

This API endpoint returns deployment status and logs based on deployment unique identifier.

Deployment - Cancel

This API endpoint interrupts and cancels a pending deployment based on unique deployment identifier.

Package store - Upload package

Use this API endpoint to upload a package to the built-in workspace package store. Every workspace has its own package store.

This endpoint accepts files and text data at the same time. For this reason you must send the payload as form-data. Read more on MDN: Sending form data - Learn web development | MDN

Supported package types:

• NuGet (*.nupkg)
• zip
• tar
• tar.gz

This endpoint will read uploaded file name to determine:

• Package type by looking at the file extensions (see above).
• Pacakge version by looking at the filename suffix that matches Semantic Versioning 2.0.0 scheme major.minor.patch-[pre-release]
• Package ID by looking at the file name after removing the extension, version and the trailing dot.

Example
‍
Uploading a file named JawsDeploy-package.1.0.5-RC2.nupkg will result in the following:
‍
Package ID: JawsDeploy-package
Version: 1.0.5-RC2
Type: NuGet

When sending the request make sure the file name follows the naming and versioning scheme explained above. The file name is important to identify the package and version correctly and avoid unnecessary duplicates in the package store. JawsDeploy supports multiple versions of the same package stored in the built-in workspace package store.