Once you understand the basics about the OpenStack REST API and have chosen a tool for sending requests to the Jetstream2 services, you can work through the examples on this page. Because the OpenStack APIs are so vast, these examples are only meant to demonstrate how a typical request is made and its response processed. Please consult the API documentation to learn more about the particular services you would like to use.

Authentication

Each time you begin an API session, you will need to authenticate your credentials with the OpenStack "Identity" service, which gives you an authentication "token" to use when making API calls to other OpenStack services. Authentication tokens are valid for one hour, after which requests will receive a 401 "Unauthorized" response until a new token is obtained.

There are numerous ways to authenticate through the Identity API, but perhaps the easiest is by passing in an "application credential", which can be obtained by Configuring an openrc.sh file. If you follow that procedure and then "source" the openrc.sh file you receive, you can use the environment variables it defines when making an authentication API call.

The request to authenticate will include a block of JSON data that specifies your application credential. You must then extract your API access token from the HTTP header of the response you receive. The JSON data you send will be similar to that in the Authenticating with an Application Credential examples. The following Bash command uses the Heredoc feature to assign the JSON body for the request into the environment variable BODY in a way that allows us to see the structure of the JSON data.

BODY=$(cat << EOF
{
  "auth":
  {
    "identity":
    {
      "methods": ["application_credential"],
      "application_credential":
      {
        "id": "$OS_APPLICATION_CREDENTIAL_ID",
        "secret": "$OS_APPLICATION_CREDENTIAL_SECRET"
      }
    }
  }
}
EOF
)

The curl command below makes the authentication request to the OpenStack REST API. The output of that command is then passed to an awk command, which extracts the returned token from the response header. The result is then assigned to the environment variable OS_TOKEN.

OS_TOKEN=$( \
  curl -s -i -X POST \
    -H "Content-Type: application/json" \
    -d "$BODY" \
    $OS_AUTH_URL/auth/tokens \
  | awk '/x-subject-token/ {print $2}' \
)

Some notes on this command:

• Curl's -s option eliminates unwanted output and its -i option includes the HTTP headers in the output. Those headers contain the "x-subject-token" value that is being captured. The -X option specifies that this is a POST request.
• Curl's -H option specifies that the data block will have type JSON.
• Curl's -d option specifies the data string for the request. We constructed the body JSON with a previous command, but it could be included on one line here (note that the body string cannot be split over multiple lines using back-slashes). It would also be possible to store your JSON string in a file and use the -d @file_name variant of this option to have curl read the string from that file.
• The URL for the request is built from the variable OS_AUTH_URL (which includes the Identity service port) and the path "/auth/tokens", which handles this particular request for a token. You may wish to define other environment variables to hold complete URLs for commonly used requests to other services.
• The response from the curl command includes the HTTP headers and JSON text. The awk command looks for a line in the headers that specifies the token and outputs only the second part of that line (the token itself).

Listing Servers in a Project

With the value of your authentication token now stored in the environment variable OS_TOKEN, you can call other services to collect information and perform actions. As an example, the following command gets a list of all "servers" (instances) in the current project.

curl -s -H "X-Auth-Token: $OS_TOKEN" \
  https://js2.jetstream-cloud.org:8774/v2/servers \
| python -m json.tool

This request returns a JSON array of server information, which is edited here to show only the entry for the instance we created with the OpenStack CLI):

{
  "servers": [
    {
      "id": "a0b63bc5-e4fe-4afa-b729-f14cbe853f5a",
      "name": "johndoe-instance",
      "links": [
        {
          "rel": "self",
          "href": "http://js2.jetstream-cloud.org:8774/v2/servers/a0b63bc5-e4fe-4afa-b729-f14cbe853f5a"
        },
        {
          "rel": "bookmark",
          "href": "http://js2.jetstream-cloud.org:8774/servers/a0b63bc5-e4fe-4afa-b729-f14cbe853f5a"
        }
      ]
    }
  ]
}

Some notes on this command:

• This curl command does not include the -i option because no important information is being returned in the HTTP headers.
• The -H header option specifies the authentication token for the request. This will be required for all service requests beyond simply getting version information. There is no header specifying a data format because there is no data for this request.
• The request URL is the service endpoint URL (including port) plus the path to the version ("/v2") and the request ("/servers").
• The JSON data that is returned is passed to Python's JSON encoder/decoderfor formatting.

If you wish to extract some information from the returned JSON, you could pipe it to a bit of Python code that finds the value of the desired path element. Below, the "id" property of the first server in the array (at index 0) is extracted using Python and then assigned to the environment variable OS_INSTANCE_ID:

OS_INSTANCE_ID=$( \
  curl -s -H "X-Auth-Token: $OS_TOKEN" \
    https://js2.jetstream-cloud.org:8774/v2/servers \
  | python -c "import sys, json; print(json.load(sys.stdin)['servers'][0]['id'])" \
)

If you are processing the data in a shell script rather than Python, you might use a program like the powerful jq to extract the data you seek:

OS_INSTANCE_ID=$( \
  curl -s -H "X-Auth-Token: $OS_TOKEN" \
    https://js2.jetstream-cloud.org:8774/v2/servers \
  | jq -r ".servers[0].id" \
)

Unshelve a Server

This final example makes a request that requires both supplying the ID of a particular entity and passing some additional data with the request. In this case, the operation is pretty simple: unshelving a shelved instance.

The ID of the instance (which was saved into an environment variable in the previous section) is added to the URL for the request. The URL rather generically asks for some "action" to be performed on the "server", and it is up to the data you pass to determine what that action is. Here is the command for this request, which does not return any data:

curl -s -H "X-Auth-Token: $OS_TOKEN" \
  -H "Content-Type: application/json" -d '{"unshelve": null}' \
  https://js2.jetstream-cloud.org:8774/v2/servers/$OS_INSTANCE_ID/action