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/

Token Authentication

Uses tokens for user authentication instead of the basic email/password authentication

Request a token for token authentication

curl -H "Content-Type: application/json" -X POST -d '{"email": "user@example.com" "password": "password123"}' https://example.com/api/v4/login/

This will return a json with an auth_token field containing the new token.

Using authentication tokens to access the api

curl -H "Content-Type: application/json" -H 'Authorization:Token (user token)' -X GET https://example.com/api/v4/

Logging out with authentication tokens

curl -H "Content-Type: application/json" -H 'Authorization:Token (user token)' -X POST https://example.com/api/v4/logout/