Rest API

Introduction

External applications can access Golive data and trigger executions of actions in Golive through its Rest API.

"External applications" can be anything: an orchestrator (like Jenkins or Bamboo), a monitoring tool (like Dynatrace or New Relic), a deployment tool (like XL Deploy or Spinnaker) or any other application that is able to use a Rest API.

All operations performed manually from the Golive User Interface (in Jira) can be automated using the Rest API.

Webhooks enables Golive to send web requests to external systems. Combining Rest API with Webhooks enables powerful bi-directional integrations!

Watch the videos

How to browse the Rest API

Use the Rest API to Replicate or Export your Environments

Use the REST API browser

In order to help you explore and use our Rest API, we have embedded a Swagger UI browser into our Jira app. From a Golive Pages, open Integration Hub:

Select HTTP or HTTPS scheme to match your Jira instance. You can then explore and try the Rest API. For instance, if we would like to add a new Environment, we can click on the "Environment" section, on the "POST /environment" section and then on the "Try it out" button:

Each time there is a example to help writing the query. Once ready, the query can be executed using the Execute button.

After the execution, the code and the response are displayed

You can copy-paste and adjust this payload in order to call the Golive Rest API from other tools.

For Jira Cloud, you will need an API token in order to call the Rest API from external tools (or from a browser that is not already logged in Jira Cloud).

API Token Authentication

Golive Rest API access requires authentication. When using the API browser from your Jira instance, your current session is used. If you want to call the API out of a browser/Jira instance, from a CI for example, you need to authenticate your calls by adding a custom HTTP header named api-key containing a Golive API token.

You can also use an api-token in a standard Bearer authentication header.

To generate token, access the API token tab from the Integration Hub menu:

Token are generated for a given user and so, impersonate this user when used. Each of the actions executed with a given token will be done on behalf the user who generated the token.

It's recommended to create a dedicated Jira technical user account only for this purpose. Permission can then be configured according to this user to decide what can be done or not with a given token.

You can see the list of already generated token, revoke & generate new ones:

In case a token has been compromised, you can revoke it and it will be rejected on next usage.

Once you have generated your token, copy to clipboard, and go to the browser API tab to open the Authorize dialog:

In the dialog just paste your token and submit it by clicking on Authorize and close the dialog:

Now, let's try it with one of the call. Expand Application section and expand the call GET /applications:

Click on Try it out to enable execution mode, and then on Execute to trigger the call:

You see at the bottom of the screen in Response Body the response returned by the web service, and if you want to execute it in a different Environment, you can copy the curl command example which shows the addition of api-key header.

Jira Cloud REST API

If you are using Golive Cloud, you may need to update values of your Environments Custom Fields when you create or edit a Jira Issue using the Jira Rest API.

The official JIRA Cloud REST API documented here.

There is nothing specific to Golive when updating your Jira issues. To help you get quicker to the point, we provide below examples of curl scripts you can adapt an re-use for your own purpose.

You need to generate an Atlassian API token and have the permission to create/update issue in order to modify/create issues using the Atlassian REST API.

Set Environments to new issue

The value of an Environment customfield is stored and set using an array of numerical ids (ex: [2,34,4])

Simply set the list of ids of the environments you want to set for an environment customfield (ex: customfield_10037), in the "fields" object at the root of the json posted as body to your POST, as in the example below:

BASH

curl --request POST \
  --url 'https://{your-domain}.atlassian.net/rest/api/3/issue' \
  --user '{user@youremail.com}:{api-token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "fields": {
    "summary": "This is a test request from Curl",
    "issuetype": {
      "id": "10004"
    },
    "project": {
      "key": "GOT"
    },
    "customfield_10037": [2,34,4]
  }
}'

Add/remove environment to issue

You can define "add" and "remove" operations in order to add/remove an environment to an existing customfield (ex: customfield_10037) of an existing issue, as in the example below:

BASH

curl --request PUT \
  --url 'https://{your-domain}.atlassian.net/rest/api/3/issue/{issueKey}' \
  --user '{user@youremail.com}:{api-token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "update": {
    "customfield_10037": [
      {
        "add": 3
      },
      {
        "remove": 4
      }
    ]
  }
}'

Set environments of an issue

You can replace all existing environments of an existing customfield (ex: customfield_10037) of an existing issue, as in the example below:

BASH

curl --request PUT \
  --url 'https://{your-domain}.atlassian.net/rest/api/3/issue/{issueKey}' \
  --user '{user@youremail.com}:{api-token}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "update": {
    "customfield_10037": [
      {
        "set": [4,5]
      }
    ]
  }
}'

Swagger.json File

You can download a swagger.json file (from the REST API browser) to generate server stubs or client SDKs in various languages:

https://swagger.io/tools/swagger-codegen

swagger.io

Automation

Using a tool like Postman (free version), you can easily use and test the Golive Rest API.

For instance, if you have hundreds of Environments in an Excel file and would like to load them in Golive, you can do it automatically with our Rest API and Postman, instead of adding them one by one from the user interface.

Here is an example of Data Import with Golive Cloud (it works similarly for Golive Server/DC)

Questions?

If you need help with your integrations, feel free to contact us.