Managing a project through an API using the cURL console utility in Linux OS

Consider the process of working with the API. It involves the following points:

Authentication using a RC file

To obtain a token ID and to proceed further with the API, you must be authenticated in SIM-Cloud. To set up the required operating system environment variables, a specially created RC file is used.

  • Create a file named ‘api-rc’ with the following content:

unset OS_TOKEN
export OS_PROJECT_DOMAIN_NAME=default
export OS_USER_DOMAIN_NAME=default
export OS_USERNAME={your_username}
# Get the password.
echo "Please enter your OpenStack Password for project $OS_PROJECT_NAME as user $OS_USERNAME: "
read -sr OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT
export OS_PROJECT_NAME={your_project_name}
export OS_IDENTITY_API_VERSION=3
export PS1='[\u@\h (SIM-CLOUD API)]\$ '
export OS_API="https://api.sim-cloud.net"
export OS_AUTH_URL=$OS_API":5000/v3"

Note

When the variables are exported from the RC file, a one-time prompt will request the password for the cloud-based project.
If you wish to suppress the password prompt and have it entered automatically, open the RC file with any text editor and change the following text block:
# Get the password.
echo "Please enter your OpenStack Password for project $OS_PROJECT_NAME as user $OS_USERNAME: "
read -sr OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT

to

export OS_PASSWORD={Your password to access the service}

Warning

Since the RC file is an ordinary text file and your password will thus be available in an unencrypted form, this approach is not secure
If you perform this step, you should set up minimum requirements rules in the system for its use.

Obtaining the token ID

  • Open the bash console, change to the catalog containing your RC file and with the aid of the ‘.’ (full stop) or ‘source’ command, export the variables from the RC file to the system environment.

source api-rc

If necessary, enter your password for your project in the SIM-Cloud.

  • You can obtain the token ID using the following command:

curl -v \
    -s \
    -X POST $OS_AUTH_URL/auth/tokens?nocatalog \
    -H "Content-Type: application/json" \
    -d '
    { "auth": {
        "identity": {
            "methods": ["password"],
            "password": {
                "user": {
                    "domain": {
                        "name": "'"$OS_USER_DOMAIN_NAME"'"},
                        "name": "'"$OS_USERNAME"'",
                        "password": "'"$OS_PASSWORD"'"
                        }
                    }
                },
        "scope": {
            "project": {
                "domain": { "name": "'"$OS_PROJECT_DOMAIN_NAME"'" }, "name": "'"$OS_PROJECT_NAME"'"
                    }
                }
            }
    }' | echo

The response received contains a line that starts ‘< X-Subject-Token:’ and the entire sequence of characters that follows constitutes the token ID for use in API requests, for example:

< X-Subject-Token: gAAAAABbcWL17tiGivJp4oc8OGiZS0Sfgn_-ZrlNzocZwTo0nfwe3Y2EbUrI-k3JfSLrIksLAKt-iFGwIhn9-JoiEL4EpTgI4WxZZPzGubDSMgoO-3wRzAm64cVr91efQU_W4JYYjxwGCqL-T4XVLncngUg7pzqJ0AHzmZB4OMXeB5dlFqDpPlE

It is then necessary to assign this value to the OS_TOKEN variable and to export this variable to the system environment.

This can all be done with a single command:

export OS_TOKEN=`curl -s -i -H "Content-Type: application/json" -X POST $OS_AUTH_URL/auth/tokens -d '{"auth": {"identity": {"methods": ["password"], "password": {"user": {"name": "'"$OS_USERNAME"'", "domain": {"name": "default"}, "password": "'"$OS_PASSWORD"'" }}}}}' | awk '/X-Subject-Token/ {print $2}'`

Sending the API request

When sending an API request, a construction of the following type is normally used:

curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" -X <METHOD> <URL> -d '{key: value}' | python -mjson.tool
where
• $OS_TOKEN - is the token ID substituted from the environment variable
• <METHOD> - is the method of transmission of the HTTP request: GET, HEAD, POST or PUT. If this is not stated, use GET
• <URL> - this is a line consisting of a combination of the symbols of the access point and parameters taken from the official documentation on the OpenStack suite
• After “-d”, specify the data structure containing the request parameters as “key:value” pairs.
• « | python -mjson.tool» - this code provides output of the response information in a readable format

For example, to work further on the project, we need to know its ID.

For this, use the following request:

curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" https://api.sim-cloud.net:5000/v3/auth/projects | python -mjson.tool
where
• $OS_TOKEN - is the token ID substituted from the environment variable
• <METHOD> - the default method (GET) is used, so we do not specify this key
• <URL> - this is a line consisting of the combination of the * URL of the access point and parameters taken from the official documentation api-ref/identity

And the following information will be received:

{
    "links": {
        "next": null,
        "previous": null,
        "self": "https://api.sim-cloud.net:5000/v3/auth/projects"
    },
    "projects": [
        {
            "description": "",
            "domain_id": "b9091e0ccd2febc3464e4d83c04be17a",
            "enabled": true,
            "id": "b1a56f59f6f013a061074fdcc56daec0",
            "is_domain": false,
            "links": {
                "self": "https://api.sim-cloud.net:5000/v3/projects/b1a56f59f6f013a061074fdcc56daec0"
            },
            "name": "demo",
            "parent_id": "b9c04be1e0cc464e4091d83d2febc37a"
        }
    ]
}
where it can be seen that
• The project name is ‘name’: demo
• The project ID - “id”: “b1a56f59f6f013a061074fdcc56daec0”

Handling the response

If the request was not successful, the error code will be issued together with an error message and short explanation of its cause:

{
    "error": {
        "code": 401,
        "message": "The request you have made requires authentication.",
        "title": "Unauthorized"
    }
}

A complete list of possible response codes and recommended actions is given in the documentation to each request, in the “Status Codes” field.