Using the Fleio 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 AngularJS.

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

The web application uses session authentication, which is based on a browser cookie. You should use tokens to authenticate when using the API from scripts.

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.

Create a token

To create an authentication token for user demoadmin follow these steps:

  1. Connect via SSH to the machine where Fleio is installed and activate the virtual environment.
  2. Enter into the Django shell.
  3. Create the token:
>>> Token.objects.create(user=AppUser.objects.get(username='demoadmin'))
<Token: 4e93e9b8e5072259856249e7ad5a7a1f2222cfa9>

Additionally, you can create a new token by accessing the django admin. Please see 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.

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'.

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

The staff API URL 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 see what requests are made while you navigate the Fleio web interface.

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

List all clients

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
}

Create a new client

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
}

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

Create an instance

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

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:

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
}

With the instance UUID we can:

Stop an instance

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"
}

Start an instance

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"
}