Intermediate 3: The Upsun API

Overview

You may find yourself wanting to build more custom tools that interact directly with the Upsun API to manage your projects and environments. Once you have retrieved an API token, you will be able to do so.

Authentication

Retrieve an API token from the management console by clicking your name in the top right hand corner of the screen and selecting My profile. Then, select the API TOKENS tab near the top of the screen.

+ Create an API Token and copy it for use in the next command.

$ curl -u upsun-api-user: \
> -d 'grant_type=api_token&api_token=YOUR_API_TOKEN' \
> https://auth.api.upsun.com/oauth2/token

This command will use your API token to retrieve an OAuth2 token, which you will be able to use to place subsequent requests on your projects and environments:

{
    "access_token": "abcdefghij1234567890",
    "expires_in": 900,
    "token_type": "bearer"
}

For example, listing your account details

curl -H "Authorization: Bearer abcdefghij1234567890" \
    https://api.upsun.com/users/me

Subscriptions and organizations

The CLI handles a lot of logic behind the scenes when you retrieve information about projects and environments. After you’ve authenticated, the CLI already has everything it needs to understand which projects you have access to based on the organizations (which include your own username) that you have access to.

Projects themselves are tied to a larger entity that includes billing and plan details called subscriptions, which are circumvented when you provide a project ID to CLI commands. Since we’re authenticating ourselves, many common commands may need a few more steps to execute.

Some commands assume that you have the JSON utility tool jq installed locally. jq is installed by default in all runtime containers on Upsun, and can be useful generally parsing API responses.

Example: adding a project-level environment variable

Let’s say that we’d like to add an environment-level variable to one of your client’s projects. In this example, let’s assume that we don’t know the project ID, but know some other details so we can locate it. As an agency, we know the names of the organization the client belongs to (customers), as well as the title of the project, which is the client’s name (Supply Nation). An API token has been exported the environment under the variable name UPSUN_CLI_TOKEN.

1. Define some variables based on what we know

   ORG_NAME=customers
   CLIENT_NAME="Supply Nation"
   

2. Retrieve an OAuth2 token to make requests

   AUTH=$(curl -s -u upsun-api-user: \
       -d "grant_type=api_token&api_token=$UPSUN_CLI_TOKEN" \
       https://auth.api.upsun.com/oauth2/token)
   TOKEN=$(echo $AUTH | jq -r '.access_token')
   

3. Get my account ID

   USER_ID=$(curl -sH "Authorization: Bearer $TOKEN" \
       https://api.upsun.com/users/me | jq -r '.id')
   

4. Retrieve organization ID client project belongs to

   ORG_ID=$(curl -sH "Authorization: Bearer $TOKEN" \
       https://api.upsun.com/users/$USER_ID/organizations | \
       jq -r --arg ORGID "$ORG_NAME" \
       '.items[] | select(.name == $ORGID) | .id')
   

   The --arg flag is used to pass bash variables into jq.

5. Get the project ID from the subscriptions API

   CLIENT_PROJECTID=$(curl -sH "Authorization: Bearer $TOKEN" \
       https://api.upsun.com/organizations/$ORG_ID/subscriptions | \
       jq -r --arg TITLE "$CLIENT_NAME" \
       '.items[] | select(.project_title == $TITLE) | .project_id')
   

6. Add the project-level variable (env:DEPLOY/friday)

   ENVVAR_KEY=DEPLOY
   ENVVAR_VALUE=friday
   
   IS_JSON=0
   IS_SENSITIVE=0
   VISIBLE_BUILD=1
   VISIBLE_RUNTIME=1
   
   # Adds a prefix to the variable name.
   VAR_KEY="env:$ENVVAR_KEY"
   
   HEADER="Content-Type: application/json"
   RESPONSE=$(curl -s -X POST \
       -H "$HEADER" -H "Authorization: Bearer $TOKEN" \
       -d '{
           "name": "'"$VAR_KEY"'",
           "value": "'"$ENVVAR_VALUE"'",
           "is_json": "'"$IS_JSON"'",
           "visible_build": "'"$VISIBLE_BUILD"'",
           "visible_runtime": "'"$VISIBLE_RUNTIME"'",
           "is_sensitive": "'"$IS_SENSITIVE"'"
       }' \
       https://api.upsun.com/projects/$CLIENT_PROJECTID/variables)
   

7. Verify variable has been added

   curl -sH "Authorization: Bearer $TOKEN" \
       https://api.upsun.com/projects/$CLIENT_PROJECTID/variables/$VAR_KEY | jq -r '.value'
   

Which will output the value of our added variable, friday. Below you can view the full script.

#!/usr/bin/env bash

# 0. Some variables.
ORG_NAME=customers
CLIENT_NAME="Supply Nation"

# 1. Retrieve an OAuth2 token to make requests.
AUTH=$(curl -s -u upsun-api-user: \
    -d "grant_type=api_token&api_token=$UPSUN_CLI_TOKEN" \
    https://auth.api.upsun.com/oauth2/token)
TOKEN=$(echo $AUTH | jq -r '.access_token')

# 2. Retrieve my account ID.
USER_ID=$(curl -sH "Authorization: Bearer $TOKEN" \
    https://api.upsun.com/users/me | jq -r '.id')

# 3. Retrieve organization ID that the client's project belongs to from it's name.
ORG_ID=$(curl -sH "Authorization: Bearer $TOKEN" \
    https://api.upsun.com/users/$USER_ID/organizations | \
    jq -r --arg ORGID "$ORG_NAME" \
    '.items[] | select(.name == $ORGID) | .id')

# 4. Retrieve client's project ID from subscriptions API.
CLIENT_PROJECTID=$(curl -sH "Authorization: Bearer $TOKEN" \
    https://api.upsun.com/organizations/$ORG_ID/subscriptions | \
    jq -r --arg TITLE "$CLIENT_NAME" \
    '.items[] | select(.project_title == $TITLE) | .project_id')

# 5. Add a project-level variable
ENVVAR_KEY=DEPLOY
ENVVAR_VALUE=friday

IS_JSON=0
IS_SENSITIVE=0
VISIBLE_BUILD=1
VISIBLE_RUNTIME=1

# Adds a prefix to the variable name.
VAR_KEY="env:$ENVVAR_KEY"

HEADER="Content-Type: application/json"
RESPONSE=$(curl -s -X POST \
    -H "$HEADER" -H "Authorization: Bearer $TOKEN" \
    -d '{
        "name": "'"$VAR_KEY"'",
        "value": "'"$ENVVAR_VALUE"'",
        "is_json": "'"$IS_JSON"'",
        "visible_build": "'"$VISIBLE_BUILD"'",
        "visible_runtime": "'"$VISIBLE_RUNTIME"'",
        "is_sensitive": "'"$IS_SENSITIVE"'"
    }' \
    https://api.upsun.com/projects/$CLIENT_PROJECTID/variables)

# 6. Verify variable added.
curl -sH "Authorization: Bearer $TOKEN" \
    https://api.upsun.com/projects/$CLIENT_PROJECTID/variables/$VAR_KEY | jq -r '.value'

Next steps

Now you’re familiar with two important tools you will use to interact with your projects and organizations: the CLI and the API.

With these in hand, let’s move onto something interesting: Multi-application projects.