===================
Using the Fleio API
===================

.. index:: backend, api, python, django, drf, rest

.. _using-api:

Fleio is built entirely on an API. Fleio backend provides an API (built with Python, Django and Django REST Framework)
and the frontend (the browser application) is built with Angular.

Everything you can do in the user interface you can also do via the Fleio API.

To use the Fleio backend API from a script, you need a an authentication token.

Token authentication
--------------------

An authentication token is a simple UUID (Universal Unique Identifier) associated to a Fleio user. Here's how an UUID
looks like: ``4e93e9b8e5072259856249e7ad5a7a1f2222cfa9``

Authentication tokens are used instead of passwords and are handy when using Fleio API from scripts or other software
that you write and interacts with Fleio.

Fleio can use both Django Rest Framework auth tokens or internal Fleio Tokens to authenticate API requests. When using
the latter, you can have multiple tokens for the same user.

Create a DRF token
==================

Connect via SSH to the machine where Fleio is installed and create an authentication token associated with a staff user:

.. code-block:: bash

    >>> echo "Token.objects.create(user=AppUser.objects.get(email='staff@domain.com'))" | fleio shell
    ...
    <Token: 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9>


Alternatively, you can create a new token by accessing the django admin. Please see :doc:`/configuring/django-admin` in
order to enable the django-admin interface.

After that, you need to access the django admin at {{ your-url }}/backend/admin/ and go to the AUTH TOKEN tab -> Tokens
and add a new token using the "ADD TOKEN" button on top right corner.

Note: you can create just one token per user, while Fleio Token supports multiple ones.


Create a Fleio API token
========================

Connect via SSH to the machine where Fleio is installed and create a Fleio token associated with a staff user:

.. code-block:: bash

    >>> echo "FleioToken.objects.create(user=AppUser.objects.get(email='staff@domain.com'))" | fleio shell
    ...
    <FleioToken: stc665c1b9f13e5623af643d3c10916442cd0b0c>


Alternatively, you can create a new token by accessing the django admin. Please see :doc:`/configuring/django-admin` in
order to enable the django-admin interface.

After that, you need to access the django admin at {{ your-url }}/backend/admin/ and go to the FLEIO CORE APP tab ->
Fleio tokens and add a new token using the "ADD FLEIO TOKEN" button on top right corner. When adding the token, make
sure that "Frontend" is not checked.


API curl examples
-----------------

You can now make simple ``GET``, ``POST``, ``PUT`` or ``DELETE`` HTTP requests by using ``curl``. Make sure you include
the authorization header as ``curl`` parameter:

* ``-H 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9'`` when using DRF token
* ``-H 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c'`` when using Fleio token

You can pipe the output to the ``json_pp`` utility to get a nicely formatted JSON.

The staff API URL is located under ``/staffapi`` and the end-user API is under ``/api``.

If you're not sure what is the full URL to your backend API or to find out specific URLs for the API requests you want
to make :ref:`see what requests are made while you navigate the Fleio web interface <see-api-requests>`.

**Make sure you don't include a trailing slash in the request URL as it may not work.**

List all clients
================

.. code-block:: bash

    curl {{ your backend url }}/staffapi/clients \
        --silent \
        --header 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9' \
        | json_pp
    {
       "count" : 3,
       "next" : null,
       "previous" : null,
       "objects" : [
          {
             "last_name" : "Demo2",
             "date_created" : "2019-11-21T16:43:25.073366+02:00",
             "phone" : "453453456t56",
             "city" : "vsdfvg",
             "long_name" : "My Co (Demo2 Demo2)",
             "first_name" : "Demo2",
             "uptodate_credit" : "0.00",
             "vat_id" : "DE9090909090",
             "country_name" : "Germany",
             "group_name" : "",
             "company" : "My Co",
             "currency" : "EUR",
             "country" : "DE",
             "state" : "sadfvgsd",
             "outofcredit_datetime" : null,
             "name" : "Demo2 Demo2",
             "configuration_name" : "",
             "email" : "demo2@demo2.com",
             "id" : 322208,
             "suspend_instead_of_terminate" : false,
             "status" : "active"
          },
          {
             "country_name" : "Switzerland",
             "group_name" : "",
             "company" : "Die Firma GmbH",
             "country" : "CH",
             "currency" : "EUR",
             "last_name" : "Test",
             "date_created" : "2019-09-13T11:30:41.443349+03:00",
             "phone" : "0267123456",
             "city" : "Cluj-Napoca",
             "long_name" : "Die Firma GmbH (Emil232663 Test)",
             "uptodate_credit" : "100.00",
             "first_name" : "Emil232663",
             "vat_id" : "CHE-909.222.212",
             "id" : 765823,
             "suspend_instead_of_terminate" : false,
             "status" : "active",
             "state" : "Cluj",
             "outofcredit_datetime" : null,
             "name" : "Emil232663 Test",
             "configuration_name" : "",
             "email" : "emil232663@duhan.com"
          },
          {
             "long_name" : "Demo Demo",
             "first_name" : "Demo",
             "uptodate_credit" : "13674.00",
             "vat_id" : null,
             "date_created" : "2019-06-06T11:27:06.543770+03:00",
             "last_name" : "Demo",
             "phone" : "89898989",
             "city" : "jhjh",
             "company" : null,
             "currency" : "EUR",
             "country" : "RO",
             "country_name" : "Romania",
             "group_name" : "",
             "configuration_name" : "",
             "email" : "demo@fleiobogustest.com",
             "state" : "ujhjhjh",
             "outofcredit_datetime" : null,
             "name" : "Demo Demo",
             "status" : "active",
             "id" : 599151,
             "suspend_instead_of_terminate" : false
          }
       ],
       "totalCount" : 3,
       "pageNo" : 1
    }


Or same command with Fleio token:

.. code-block:: bash

    curl {{ your backend url }}/staffapi/clients \
        --silent \
        --header 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c' \
        | json_pp


Create a new client
===================

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9' \
        --header 'Content-Type: application/json' \
        {{ your backend url }}/staffapi/clients \
        --data '{"address1": "99 Elm St.", "city": "New York", "country": "US", "create_auto_order_service": true, "currency": "EUR", "email": "jane@doe.com", "first_name": "Jane", "last_name": "Doe", "phone": "9999999", "state": "NY", "zip_code": "1000"}' \
        | json_pp
    {
       "external_billing_id" : null,
       "create_auto_order_service" : false,
       "address2" : null,
       "last_name" : "Doe",
       "custom_fields" : [],
       "address1" : "99 Elm St.",
       "zip_code" : "1000",
       "id" : 722694,
       "first_name" : "Jane",
       "reseller_client" : 0,
       "fax" : null,
       "country" : "US",
       "phone" : "9999999",
       "configuration" : "default",
       "city" : "New York",
       "currency" : "EUR",
       "company" : null,
       "groups" : [],
       "auto_order_service_external_billing_id" : null,
       "state" : "NY",
       "email" : "jane@doe.com",
       "vat_id" : null
    }

Or same command with Fleio token:

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c' \
        --header 'Content-Type: application/json' \
        {{ your backend url }}/staffapi/clients \
        --data '{"address1": "99 Elm St.", "city": "New York", "country": "US", "create_auto_order_service": true, "currency": "EUR", "email": "jane@doe.com", "first_name": "Jane", "last_name": "Doe", "phone": "9999999", "state": "NY", "zip_code": "1000"}' \
        | json_pp

You can see in the response the newly generated client ID: ``722694``. Let's create an OpenStack compute instance and
assign it to this new client.


Create an instance
==================

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9' \
        --header 'Content-Type: application/json' \
        {{ your backend url }}/staffapi/openstack/instances \
        --data '{"region":"Region1","share_image":false,"nics":["d9f9ca07-3ce5-435e-8aa2-a7302697025d"],"client":722694,"boot_source":{"source_type":"image","source_id":"b8e54aa5-eca9-454a-adaf-00fbc659755e","delete_on_termination":false,"create_new_volume":false,"volume_type":""},"name":"newinstance","flavor":"fd6ebb42-f305-4eb7-b086-fcce39bc761f"}' \
        | json_pp

Or same command with Fleio token:

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c' \
        --header 'Content-Type: application/json' \
        {{ your backend url }}/staffapi/openstack/instances \
        --data '{"region":"Region1","share_image":false,"nics":["d9f9ca07-3ce5-435e-8aa2-a7302697025d"],"client":722694,"boot_source":{"source_type":"image","source_id":"b8e54aa5-eca9-454a-adaf-00fbc659755e","delete_on_termination":false,"create_new_volume":false,"volume_type":""},"name":"newinstance","flavor":"fd6ebb42-f305-4eb7-b086-fcce39bc761f"}' \
        | json_pp


Get client's instance list
==========================

After we wait a while for the instance to actually be created, we can get the newly created instance UUID by listing
this client's instances:

.. code-block:: bash

    curl --request GET \
        --silent --show-error \
        --header 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9' \
        {{ your backend url }}/staffapi/openstack/instances?filtering=project__service__client__id:722694 \
        | json_pp
    {
       "permissions" : {
          "instances.abort-migrate" : true,
          "instances.detach_volume" : true,
          "instances.rename" : true,
          "instances.add_floating_ip" : true,
          "instances.revert-resize" : true,
          "instances.change-password" : true,
          "instances.create_snapshot" : true,
          "instances.suspend" : true,
          "instances.move" : true,
          "instances.create_backup" : true,
          "instances.associate_security_group" : true,
          "instances.rescue" : true,
          "instances.unrescue" : true,
          "instances.remove_floating_ip" : true,
          "instances.stop" : true,
          "instances.migrate" : true,
          "instances.attach-volume" : true,
          "instances.resize" : true,
          "instances.start" : true,
          "instances.boot_from_iso" : true,
          "instances.resume" : true,
          "instances.reboot" : true,
          "instances.create" : true,
          "instances.dissociate_security_group" : true,
          "instances.reset-state" : true,
          "instances.destroy" : true,
          "instances.lock" : true,
          "instances.confirm-resize" : true,
          "instances.unlock" : true,
          "instances.rebuild" : true
       },
       "next" : null,
       "previous" : null,
       "objects" : [
          {
             "status" : "active",
             "os_distro" : null,
             "flavor" : {
                "description" : "m1.tiny",
                "memory_gb" : 0.25,
                "properties" : "{}",
                "region" : "Region1",
                "out_of_stock" : false,
                "vcpus" : 1,
                "used_by_resellers" : [],
                "memory_mb" : 256,
                "id" : "fd6ebb42-f305-4eb7-b086-fcce39bc761f",
                "root_gb" : 1,
                "swap" : 0,
                "ephemeral_gb" : 0,
                "name" : "m1.tiny",
                "reseller_resources" : null,
                "flavor_group" : {
                   "name" : "Local storage",
                   "id" : 1,
                   "priority" : 10
                }
             },
             "booted_from_iso" : false,
             "host_name" : "Region1-compute.fleio.org",
             "name" : "newinstance",
             "current_month_traffic" : 0,
             "client" : {
                "name" : "Jane Doe",
                "id" : 722694
             },
             "created" : "2019-11-27T14:36:45+02:00",
             "hostId" : "30e22192fc4ca6ee560afe0b1b42502c76f23dd25ae7722d320b3369",
             "allowed_actions" : [
                "reboot",
                "shutoff",
                "resize",
                "rescue",
                "rebuild",
                "console",
                "rename",
                "create_snapshot",
                "suspend",
                "add_port",
                "remove_port",
                "add_ip",
                "remove_ip",
                "migrate",
                "abort_migrate",
                "attach_volume",
                "move",
                "boot_from_iso",
                "lock",
                "unlock",
                "associate_ip",
                "dissociate_ip",
                "change_password"
             ],
             "uuid" : "a623787b-d529-4681-9c51-6abcf3b5a4d8",
             "region" : "Region1",
             "description" : null,
             "region_obj" : {
                "id" : "Region1",
                "enable_volumes" : true,
                "description" : "",
                "enable_snapshots" : true,
                "enabled" : true
             },
             "current_cycle_traffic" : 0,
             "access_ip" : "192.168.40.174",
             "display_status" : "Running",
             "locked" : false,
             "image" : "b8e54aa5-eca9-454a-adaf-00fbc659755e",
             "display_task" : null,
             "id" : "a623787b-d529-4681-9c51-6abcf3b5a4d8"
          }
       ],
       "count" : 1,
       "pageNo" : 1,
       "totalCount" : 1
    }

Or same command with Fleio token:

.. code-block:: bash

    curl --request GET \
        --silent --show-error \
        --header 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c' \
        {{ your backend url }}/staffapi/openstack/instances?filtering=project__service__client__id:722694 \
        | json_pp

With the instance UUID we can:

Stop an instance
================

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9' \
        {{ your backend url }}/staffapi/openstack/instances/a623787b-d529-4681-9c51-6abcf3b5a4d8/stop \
        | json_pp
    {
       "detail" : "Instance is stopping"
    }

Or same command with Fleio token:

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c' \
        {{ your backend url }}/staffapi/openstack/instances/a623787b-d529-4681-9c51-6abcf3b5a4d8/stop \
        | json_pp
    {
       "detail" : "Instance is stopping"
    }


Start an instance
=================

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Token 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9' \
        {{ your backend url }}/staffapi/openstack/instances/a623787b-d529-4681-9c51-6abcf3b5a4d8/start \
        | json_pp
    {
       "detail" : "Instance is starting"
    }

Or same command with Fleio token:

.. code-block:: bash

    curl --request POST \
        --silent --show-error \
        --header 'Authorization: Fleio-Token stc665c1b9f13e5623af643d3c10916442cd0b0c' \
        {{ your backend url }}/staffapi/openstack/instances/a623787b-d529-4681-9c51-6abcf3b5a4d8/start \
        | json_pp
    {
       "detail" : "Instance is starting"
    }