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 :

{
  "message": "Client must be authenticated to access this resource.",
  "status-code": 401
}

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)

{
  "versionName": "ECOM 1.2.8"
}

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

(200) OK Response

{
  "deploymentId": 20,
  "environmentId": 1,
  "deployer": "admin",
  "categoryId": 5,
  "categoryName": "Staging",
  "applicationId": 1,
  "applicationName": "eCommerce",
  "versionName": "ECOM 1.2.6",
  "deployedTime": 1430683616682
}

KO Response examples

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

{
  "errorMessages": [
    "Could not find any application with name=eCommerce Bad Name"
  ],
  "errors": {}
}

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

{
  "errorMessages": [
    "User=admin is not allowed to deploy a version into this environment (application=eCommerce,category=Staging)."
  ],
  "errors": {}
}

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

{
  "deploymentId": 20,
  "environmentId": 1,
  "deployer": "admin",
  "categoryId": 5,
  "categoryName": "Staging",
  "applicationId": 1,
  "applicationName": "eCommerce",
  "versionName": "ECOM 1.2.6",
  "deployedTime": 1430683616682
}

KO Response examples

(400) Unknown id :

{
 "errorMessages": [
 "Could not find any deployment with id=7897"
 ],
 "errors": {}
}


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

[
  {
    "deploymentId": 18,
    "deployer": "admin",
    "categoryId": 5,
    "categoryName": "Staging",
    "applicationId": 8,
    "applicationName": "eCommerce2",
    "versionName": "ECOM 1.2",
    "deployedTime": 1430679375122
  },
  {
    "deploymentId": 3,
    "deployer": "admin",
    "categoryId": 5,
    "categoryName": "Staging",
    "applicationId": 8,
    "applicationName": "eCommerce2",
    "versionName": "ECOM 2.4bet343",
    "deployedTime": 1430430065924
  }
]

KO Response Example

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

{
  "errorMessages": [
    "Could not find any application with name=eCommerce Bad Name"
  ],
  "errors": {}
}

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 :

{
   "id":3
}

Using the name of the new status to set :

{
   "name":"Available"
}

Using empty JSON to set an empty/unknown status

{
}

(200) OK Response

{
  "id": 8,
  "categoryId": 10,
  "categoryName": "Staging",
  "applicationId": 1,
  "applicationName": "eCommerce",
  "statusName": "Unavailable",
  "changedBy": "admin",
  "changedOn": 1478450508794,
  "status": {
    "id": 3,
    "name": "Unavailable",
    "description": "Environment is unavailable",
    "color": "RED"
  }
}

KO Response Examples

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

{
  "errorMessages": [
    "Could not find any application with name=eCommerce Bad Name"
  ],
  "errors": {}
}

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

{
  "errorMessages": [
    "User=admin is not allowed to update the status of this environment (application=eCommerce,category=Staging)."
  ],
  "errors": {}
}

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

[
  {
    "id": 8,
    "categoryId": 10,
    "categoryName": "Staging",
    "applicationId": 1,
    "applicationName": "eCommerce",
    "statusName": "Unavailable",
    "changedBy": "admin",
    "changedOn": 1478450508794,
    "status": {
      "id": 3,
      "name": "Unavailable",
      "description": "Environment is unavailable",
      "color": "RED"
    }
  },
  {
    "id": 7,
    "categoryId": 10,
    "categoryName": "Staging",
    "applicationId": 3,
    "applicationName": "Payment Service",
    "statusName": "Available",
    "changedBy": "admin",
    "changedOn": 1478450502895,
    "status": {
      "id": 1,
      "name": "Available",
      "description": "Environment is available",
      "color": "GREEN"
    }
  }
]

KO Response Example

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

{
  "errorMessages": [
    "Could not find any application with name=eCommerce Bad Name"
  ],
  "errors": {}
}

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

{
  "url": "http://newURL",
  "customProperties": [
    {
      "key": "PROPERTY_1",
      "value": "New value for property 1"
    },
    {
      "key": "PROPERTY_2",
      "value": "New value for property 2"
    },
    {
      "key": "PROPERTY_3",
      "value": "New value for property 3"
    }
  ],
  "application": {
    "name": "ERP"
  },
  "category": {
    "name": "Demo"
  },
  "environmentPermissionScheme": {
    "id": 1
  }
}

POST / GET / PUT (200) OK Response Example

{
  "id": 1,
  "url": "http://newURL",
  "urlHtml": "<a href=\"http://newURL\" target=\"_blank\">http://newURL</a>",
  "customProperties": [
    {
      "id": 1,
      "key": "PROPERTY_1",
      "name": "Description",
      "description": "General information about the environment, purpose of the environment,...",
      "active": true,
      "value": "New value for property 1",
      "valueHtml": "New value for property 1"
    },
    {
      "id": 2,
      "key": "PROPERTY_2",
      "name": "Details",
      "description": "Detailed information about the environment (ex : link on admin console, administrator,...)",
      "active": true,
      "value": "New value for property 2",
      "valueHtml": "New value for property 2"
    },
    {
      "id": 3,
      "key": "PROPERTY_3",
      "name": "Configuration",
      "description": "Details about the confirmation of the environment (ex: OS, DB engine, app server, link on external configuration tool,..",
      "active": false,
      "value": "New value for property 3",
      "valueHtml": "New value for property 3"
    }
  ],
  "application": {
    "id": 2,
    "name": "ERP"
  },
  "category": {
    "id": 5,
    "name": "Test"
  },
  "environmentPermissionScheme": {
    "id": 1,
    "name": "Default EnvironmentPermission Scheme"
  }
}

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

[
  {
    "id": 3,
    "url": "http://dev1-company.com/shop",
    "urlHtml": "<a href=\"http://dev1-company.com/shop\" target=\"_blank\">http://dev1-company.com/s..</a>",
    "customProperties": [
      {
        "id": 3,
        "key": "PROPERTY_3",
        "name": "Configuration",
        "description": "Details about the confirmation of the environment (ex: OS, DB engine, app server, link on external configuration tool,..",
        "active": false
      },
      {
        "id": 1,
        "key": "PROPERTY_1",
        "name": "Description",
        "description": "General information about the environment, purpose of the environment,...",
        "active": true,
        "value": "",
        "valueHtml": ""
      },
      {
        "id": 2,
        "key": "PROPERTY_2",
        "name": "Details",
        "description": "Detailed information about the environment (ex : link on admin console, administrator,...)",
        "active": false,
        "value": "Fred's Mac Mini.\r\nOwner:fred@your-company.com\r\nCMS:https://dev1-company.com/shop/admin",
        "valueHtml": "Fred's Mac Mini. \n<br> Owner:\n<a href=\"mailto:fred@your-company.com\">fred@your-company.com</a> \n<br> CMS:\n<a href=\"https://dev1-company.com/shop/admin\" target=\"_blank\">https://dev1-company.com/..</a>"
      }
    ],
    "application": {
      "id": 1,
      "name": "eCommerce"
    },
    "category": {
      "id": 1,
      "name": "Dev 1"
    },
    "environmentPermissionScheme": {
      "id": 1,
      "name": "Default EnvironmentPermission Scheme"
    }
  },
  {
    "id": 4,
    "url": "",
    "urlHtml": "",
    "customProperties": [
      {
        "id": 3,
        "key": "PROPERTY_3",
        "name": "Configuration",
        "description": "Details about the confirmation of the environment (ex: OS, DB engine, app server, link on external configuration tool,..",
        "active": false
      },
      {
        "id": 1,
        "key": "PROPERTY_1",
        "name": "Description",
        "description": "General information about the environment, purpose of the environment,...",
        "active": true,
        "value": "",
        "valueHtml": ""
      },
      {
        "id": 2,
        "key": "PROPERTY_2",
        "name": "Details",
        "description": "Detailed information about the environment (ex : link on admin console, administrator,...)",
        "active": false,
        "value": "",
        "valueHtml": ""
      }
    ],
    "application": {
      "id": 1,
      "name": "eCommerce"
    },
    "category": {
      "id": 2,
      "name": "Dev 2"
    },
    "environmentPermissionScheme": {
      "id": 1,
      "name": "Default EnvironmentPermission Scheme"
    },
    "status": {
      "id": 3,
      "name": "Unavailable",
      "description": "Environment is unavailable"
    }
  }
]

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.

{
  "watchDeployedVersion": true,
  "watchStatus": false,
  "watchIssueAdded": false,
  "watchIssueRemoved": false
}

POST / PUT / GET (200) OK Response Example

{
  "id": 14,
  "userName": "admin",
  "environmentId": 2,
  "watchDeployedVersion": true,
  "watchStatus": false,
  "watchIssueAdded": false,
  "watchIssueRemoved": false
}

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


$ curl -s -u : -X POST -H "Content-Type: application/json" --data '{"watchDeployedVersion":true,"watchStatus":true,"watchIssueAdded":true,"watchIssueRemoved":true}' "https://your-jira-base-url/rest/holydev/1.0/watcher/user?environmentId=1&userName=fred"
# Will add user "fred" as watcher of environment with id=1 with 4 watch options activated

$ curl -s -u : -X DELETE -H "Content-Type: application/json" "https://your-jira-base-url/rest/holydev/1.0/watcher/user?environmentId=1&userName=fred"
# Will remove user "fred" as watcher of environment with id=1

$ curl -s -u : -X GET -H "Content-Type: application/json" "https://your-jira-base-url/rest/holydev/1.0/watcher/user?environmentId=1&userName=fred"
# Will return OK if user "fred" is a watcher of environment with id=1