Workflow

Making requests

The API workflow consists of making an HTTP request to an endpoint, and processing the response:

Any 2xx response code indicates success.
Any other response code indicates an error. Typically this will be a 4xx response code, and will return a JSON payload with a key of "error" and a message about what happened:

Example JSON error message

 { "error": "missing slice name" }

Example Code Blocks

Every endpoint description in this document includes an example code block. Hovering your mouse over a code block will reveal a clipboard button you can click to copy the code, and paste it into a script or prompt.

Examples use the curl command. The code example below is an API call to list all of your slices. Feel free to try it right now, replacing $API_TOKEN with your token:

Curl

 curl --request GET \
      --url https://cloud.syminet.com/api/v1/slices \
      --header "authorization:bearer $API_TOKEN"

If you do not have any slices, you should get a JSON response like this:

List slices when there aren’t any.

 {"data":[],"page":0,"pages":0,"results":0}

Or if you do have some slices, it should return a JSON payload listing them.

Formatting JSON Responses

When working at CLI it can be much nicer to “pretty print” JSON responses into human-readable form. Python is available on all linux distributions, and you can pipe the response into is using python’s json.tool. Here is an example of the above request, piping through python:

Curl

 curl --request GET \
      --url https://cloud.syminet.com/api/v1/slices \
      --header "authorization:bearer $API_TOKEN" | python3 -m json.tool

An alternative to python is the jq program, which is also available on all major linux distributions:

Curl

 curl --request GET \
      --url https://cloud.syminet.com/api/v1/slices \
      --header "authorization:bearer $API_TOKEN" | jq

Environment

Pasting your $API_TOKEN every time can get tiresome. If you are at a linux shell, you can use the export command to add $API_TOKEN to your environment. For example, if your API token is MY_TOKEN, you would enter this at your prompt:

Add $API_TOKEN to your environment

export API_TOKEN="MY_TOKEN"

Subsequent commands (curl, etc.) or scripts containing $API_TOKEN, will have your token auto-filled. This documentation uses this form to help with simply copy/pasting the examples.

Hint

Taking it a step further, you can append the export command to your .bashrc file so that it is automatically available every time you get a shell prompt.

Caution

Beware of running any commands containing your token on shared systems with multiple users, as they will be able to see your token via commands like ps and others. Only run commands containing your token on machines where you are the only user.