=============
API examples
=============

These examples use the command-line application cURL with JSON data. The
management server is assumed to be located at https://example.com/ with
a user whose username is "api" having password "pword".

.. note::
    ``curl`` has a few command line switches used throughout these examples:

    -  ``-H`` specify extra headers
    -  ``-u`` username and password authentication
    -  ``-X`` request method, which defaults to GET
    -  ``-d`` specify which data to send as POST (or PUT or PATCH). If it
       starts with an "@" will send the contents of that file.
    -  ``-k`` don't verify server SSL certificate

Aggregators
------------

Listing aggregators
++++++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/aggregators/

Get all bonds on aggregator 1
++++++++++++++++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/aggregators/1/bonds/

Bonders
--------

Bonders contain the name, username, and password fields that are visible
in the regular web config. Other fields are found in the bond object.

Listing bonders
++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonders/

Update bonder 8 with changes from a file
+++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Content-Type: application/json" -X PUT -d "@bonder.json" https://example.com/api/v4/bonders/8/

Bonds
------

When you create a bond, a bonder object is automatically created with
the name "default-<some random 8-character string>". Be sure to change
the name to something real.

Listing bonds
++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonds/

Get bond 3
++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonds/3/

Update bond 3 with changes from a file
++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Accept: application/json" -H "Content-Type: application/json" -X PUT -d "@bond.json" https://example.com/api/v4/bonds/3/

Create a new bond
++++++++++++++++++

When creating a new bond, a bonder object is created automatically. You
can then update the bonder object as necessary.

::

    curl -u api:pword -H "Content-Type: application/json" -X POST -d "@bond.json" https://example.com/api/v4/bonds/

Restart bond 3
++++++++++++++++

::

    curl -u api:pword -X POST https://example.com/api/v4/bonds/3/restart/

Delete bond 3
+++++++++++++++

When deleting a bond, the accompanying bonder is also deleted.

::

    curl -u api:pword -X DELETE https://example.com/api/v4/bonds/3/

Disable Quality of Service for bond 3
+++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Content-type: application/json" -X PATCH -d '{"qos_profile": null}' https://example.com/api/v4/bonds/3/

Change Quality of Service profile for bond 3
++++++++++++++++++++++++++++++++++++++++++++++

To change the Quality of Service profile for a bond, submit as the value
of the qos_profile field the API URI of the desired profile. The URI
can be complete, with the protocol, hostname, and path, or just the
path.

::

    curl -k -u api:pword -H "Content-type: application/json" -X PATCH -d '{"qos_profile": {"url": "/api/v4/qos/1/"}}' https://example.com/api/v4/bonds/3/

Move bond 3 to a different aggregator
+++++++++++++++++++++++++++++++++++++++

::

    curl -k -u api:pword -H "Content-type: application/json" -X PATCH -d '{"aggregator": "/api/v4/aggregators/3/"}' https://example.com/api/v4/bonds/3/

Show bonds in a specific space
+++++++++++++++++++++++++++++++

Filter by space key:

::

    curl -u api:pword https://example.com/api/v4/bonds/?space__key=spckey

Filter by space name:

::

    curl -u api:pword https://example.com/api/v4/bonds/?space__name=Space Name

Filter by space CRM ID:

::

    curl -u api:pword https://example.com/api/v4/bonds/?space__crm_id=CRM ID

Legs
-----

There are two types of legs: interface and mobile broadband.

The leg list at ``/api/v4/legs/`` is a generic representation of
all legs accross all bonds.

Get a list of all interface legs on bond 3
+++++++++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonds/3/interface_legs/

Create a new interface leg on bond ID 3
+++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Content-Type: application/json" -X POST -d "@leg.json" https://example.com/api/v4/bonds/3/interface_legs/

Get interface leg 1 from bond 3
++++++++++++++++++++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonds/3/interface_legs/1/

Update interface leg 1 with changes from a file
+++++++++++++++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Content-Type: application/json" -X PUT -d "@leg.json" https://example.com/api/v4/bonds/3/interface_legs/1/


Get all DHCP addressings on bond 3
+++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonds/3/dhcp_addressings/

Renew DHCP lease for addressing 8 on bond 3
++++++++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -X POST https://example.com/api/v4/bonds/3/dhcp_addressings/8/renew/

Delete interface leg 1
++++++++++++++++++++++++

::

    curl -u api:pword -X DELETE https://example.com/api/v4/bonds/3/interface_legs/1/

Speed tests
------------

Get a list of speed tests on bond 3
+++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword https://example.com/api/v4/bonds/3/speedtests/

Create a new speed test whose target is bond on bond ID 3
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Content-Type: application/json" -X POST -d "{'target': '/api/v4/bonds/3/', 'protocol': 'tcp', 'direction': 'down', 'length': '10.0'}" https://example.com/api/v4/bonds/3/speedtests/

Create a new speed test whose target is leg ID 1 on bond ID 3
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

::

    curl -u api:pword -H "Content-Type: application/json" -X POST -d "{'target': '/api/v4/bonds/3/legs/1/', 'protocol': 'tcp', 'direction': 'down', 'length': '10.0'}" https://example.com/api/v4/bonds/3/speedtests/
