RESTFul Endpoints

Environment Manager is shipped with RESTful endpoints since Version 2.0.

Best way to understand and test the API is to open the REST browser provided by Atlassian with your JIRA installation. More information about the REST browser here : https://developer.atlassian.com/docs/developer-tools/using-the-rest-api-browser. You can usually access the REST browser of your JIRA instance using this url : https://my-jira-server-url/plugins/servlet/restbrowser#/ .



Authentication

You must be authenticated in JIRA in order to access the REST API of Environment Manager. Refer to general JIRA REST API documentation to know how to get JIRA authentication.

(401) Error returned by REST API if the user is not authenticated in JIRA :


GET / PUT – Deployment

Get deployment information or deploy a new version on to an environment.

Base URL : http//your-host:your-port/rest/holydev/1.0/deployment (GET / PUT)

Parameters

  • category (mandatory) : category of the environment (ex : staging, dev, integration,…)
  • application (mandatory) : application of the environment (ex : eCommerce, ERP,…)
  • dateTime (optional, since version 4.5) : effective date of the deployment (a PAST date with format yyyy-MM-dd HH:mm)

Body Example (PUT only)

Note : if “versionName” is not present, current deployed version (if any) will be erased (set to null).

(200) OK Response

KO Response examples

(404) Cannot find an application named “eCommerce Bad Name” :

(PUT only) (403) Connected user has not the permissions to deploy on this environment (refer to Roles and Permissions Documentation for setup)


DELETE – Deployment
(since version 4.5)

Delete a deployment

Base URL : http//your-host:your-port/rest/holydev/1.0/deployment/{id} (DELETE)

Parameters

  • id (mandatory) : id of the deployment to delete (can be found in result of GET Deployment(s) requests)

Body

No body must be sent

(200) OK Response

KO Response examples

(400) Unknown id :


GET – Search Deployments

Search in history of all deployments performed.

Base URL : http//your-host:your-port/rest/holydev/1.0/deployments (GET)

Parameters

  • category (optional) : filter by category (ex : staging, dev, integration,…)
  • application (optional) : filter by application (ex : eCommerce, ERP,…)

Note : if no parameters, all deployments will be returned default limit of number of results is set to 100

(200) OK Response Example

KO Response Example

(404) Cannot find an application named “eCommerce Bad Name” :


GET/PUT – Status Change

Since version 3.6

Get information of last status change of an environment or change the status of environment.

Base URL : http//your-host:your-port/rest/holydev/1.0/status-change (GET / PUT)

Parameters

  • category (mandatory) : category of the environment (ex : staging, dev, integration,…)
  • application (mandatory) : application of the environment (ex : eCommerce, ERP,…)

Body Examples (PUT only)

Using the id of the new status to set :

Using the name of the new status to set :

Using empty JSON to set an empty/unknown status

(200) OK Response

KO Response Examples

(404) Cannot find an application named “eCommerce Bad Name” :

(403) Connected user has not the permissions to change status of this environment (refer to Roles and Permissions Documentation for setup) :


GET – Search Status Changes

Since version 3.6

Search in history of all status changes.

Base URL : http//your-host:your-port/rest/holydev/1.0/status-changes (GET)

Parameters

  • category (optional) : filter by category (ex : staging, dev, integration,…)
  • application (optional) : filter by application (ex : eCommerce, ERP,…)
  • maxResult (optional) : limit the number of results (if not present, will return the 100 first results)

(200) OK Response Example

KO Response Example

(404) Cannot find an application named “eCommerce Bad Name” :


POST / GET / PUT – Environment

Since Version 3.2

Get/update data and custom properties of an environment.

Base URL : http//your-host:your-port/rest/holydev/1.0/environment/{id} (GET / PUT)

Create a new environment.

Base URL : http//your-host:your-port/rest/holydev/1.0/environment (POST)

POST / PUT Body Example

POST / GET / PUT (200) OK Response Example


GET – Search Environments

Since Version 3.2

Base URL : http//your-host:your-port/your-context/rest/holydev/1.0/environments (GET)

Parameters

  • no parameter : return all environments
  • application (optional) : exact name of the application
  • category (optional) : exact name of the category
  • property1 (optional) : exact value of the custom property 1
  • property2 (optional) : exact value of the custom property 2
  • property3 (optional) : exact value of the custom property 3

N.B. If you set twice the same parameter with different values, it will return all environments matching at least one of these values. For example : application=eCommerce&application=ERP will return eCommerce AND ERP environments.

(200) OK Response Example


POST / PUT / DELETE / GET – Watcher

Since Version 3.3

Add, update, remove or get a watcher of an environment.

Base URL : http//your-host:your-port/rest/holydev/1.0/watcher/user (POST / PUT / DELETE / GET)

Parameters

  • environmentId (mandatory) : id of watched environment
  • userName (optional) : username of the watcher

Note :

  • If no userName parameter is set, the logged in user is considered as watcher
  • Only jira-administrators can set a value for parameter userName

POST / PUT Body Example

Set the Watch Options. At least one must be true.

POST / PUT / GET (200) OK Response Example


CURL examples

Do not forget to adapt the examples of curl scripts provided below with :

  • a valid jira base url (ex : https://localhost:2990/jira)
  • a valid jira user’s credentials (username, password). This JIRA account used must have sufficient permissions.
  • existing application and categorie names

N.B. URL has to be put between quotes to avoid curl ignoring the URL parameters ! More information here : http://stackoverflow.com/questions/13371284/curl-command-line-url-parameters

Online curl documentation : https://curl.haxx.se/docs/manpage.html

PUT – Create / Update Deployment