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: 

.. code-block:: shell
   :caption: Example JSON error message

    { "error": "missing slice name" }

..
    * A **500** response indicates a serverside error.  Feel free to send a support request 
      if you ever see one.


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:

.. code-block:: shell
   :caption: 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:

.. code-block:: shell
   :caption: 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:

.. code-block:: shell
   :caption: 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:

.. code-block:: shell
   :caption: 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:

.. code-block:: shell
    :caption: 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.