• Print
  • Share
  • Dark
    Light

Integrations Overview and API

  • Updated on 01 Sep 2018
  • 3 minutes to read
  • Contributors

Retrace provides a simple HTTP API for tracking deployments. We have created recipes or plug-ins for some of the most popular deployment tools.

Please view their specific examples to walkthrough how to configure them. If you do not see your deployment tool listed, you can probably adapt our example scripts below within your deployment tool.

You can also use our API directly via Bash or PowerShell as part of your deployment scripts. Examples are provided below.

API Basics

Our API exposes command endpoints that can start, complete, or cancel a deployment request.

https://api.stackify.net/api/v1/deployments/start

All API requests are matched up by the specified app name, environment, and version. These should be specified in every API call.

Available fields to send via the API:

  • ApiKey - Required Stackify license key for your account so that we can identify and authenticate your account
  • AppName - Important so that Retrace can match the request to your app
  • EnvironmentName - Important so that Retrace can update the proper environment. QA, Prod, etc
  • Name - Description, name, or version for the deployment
  • Branch - The name of your branch
  • Commit - The hash of the commit to track exactly what code was deployed
  • Uri - A URL to the build or commit to easily reference
  • Version - Specify a version number of your product

All requests go through some basic validation to ensure that the states of the deployment go through the correct transition. For example, you can't cancel a deployment that hasn't started.

Please note that deployment tracking requests are queued up when they are received within Retrace. It make take up to 5 minutes to fully see the deployment in Retrace along with all of the reporting and visualization features.

Authentication

Authentication is performed by setting the request authorization header in the following format, where ApiKey is the client's specific activation key.

Authorization: ApiKey {API_KEY}

Automating Deployments with Bash

Below are examples of how to use our API with Bash.

Starting a Deployment

curl -X POST 
    https://api.stackify.net/api/v1/deployments/start 
    -H 'authorization: ApiKey  ENTER_YOUR_LICENSE_KEY' 
    -H 'content-type: application/json' 
    -d '{
        "Name": "BourneAgain",
        "Uri": "localhost",
        "Branch": "master",
        "Commit": "rOapzPyAtzUR9s7yDJYlGz2vUYbcl0P6gMVglrygJ2",
        "Version": "v1.0",
        "AppName": "FooApp",
        "EnvironmentName": "Prod"
}'

Cancel a Deployment

curl -X POST 
    https://api.stackify.net/api/v1/deployments/cancel 
    -H 'authorization: ApiKey ENTER_YOUR_LICENSE_KEY' 
    -H 'content-type: application/json' 
    -d '{
        "Version": "v1.0",
        "AppName": "FooApp",
        "EnvironmentName": "Prod"
}'

Deployment Completed

curl -X POST 
    https://api.stackify.net/api/v1/deployments/complete 
    -H 'authorization: ApiKey ENTER_YOUR_LICENSE_KEY' 
    -H 'content-type: application/json' 
    -d '{
        "Version": "v1.0",
        "AppName": "FooApp",
        "EnvironmentName": "Prod"
}'

Automating Deployments with PowerShell

Below is a PowerShell script that we put together than can be easily reused for different scenarios. We would suggest downloading this next code snippet and saving it as stackify-deploy.ps1. Below we have some examples of how you would then use it.

Param(
        [Parameter(Mandatory=$True,Position=0)]
        [ValidateSet('complete','start','cancel')]
        [string]$action,
        [Parameter(Mandatory=$True)][string]$apiKey,
        [Parameter(Mandatory=$True)][string]$version,
        [Parameter(Mandatory=$True)][string]$app,
        [Parameter(Mandatory=$True)][string]$env,
        [Parameter(Mandatory=$False)][string]$uri,
        [Parameter(Mandatory=$False)][string]$name,
        [Parameter(Mandatory=$False)][string]$branch,
        [Parameter(Mandatory=$False)][string]$commit,
        [Parameter(Mandatory=$False)][string]$hostApi
)

# build the post url
if (!$hostApi) { $hostApi= 'https://api.stackify.net' }

$post = $hostApi.TrimEnd('/') + '/api/v1/deployments/' + $action

# build the authorization header
$headers = @{'authorization'='ApiKey ' + $apiKey}

# build the body of the post
if (!$name) { $name = $version }

$bodyObj = @{ Version=$version; AppName=$app; EnvironmentName=$env; }

if ($action -eq "start" -or $action -eq "complete"){
        $bodyObj.Name = $name
        if ($uri) { $bodyObj.Uri = $uri }
        if ($branch) { $bodyObj.Branch = $branch }
        if ($commit) { $bodyObj.Commit = $commit }
}

$body = ConvertTo-Json $bodyObj

# send the request
Invoke-WebRequest -Uri $post -Method POST -ContentType "application/json" -Headers $headers -Body $body

Starting a Deployment

ps > .\stackify-deploy.ps1 start -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0" -name "BourneAgain" -branch "master" -commit "ca35857d2cc6050a2525491840922a6d5d359006" -uri "localhost"

ps > .\\stackify-deploy.ps1 complete -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0"

Cancel a Deployment

ps > .\stackify-deploy.ps1 cancel -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0"

Deployment Completed

ps > .\\stackify-deploy.ps1 complete -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0" -name "BourneAgain" -branch "master" -commit "ca35857d2cc6050a2525491840922a6d5d359006" -uri "localhost"