Rest API

From Airangel Wiki
Jump to: navigation, search

REST API v1.4 - available since release 3.4.24

The REST API provides access to guest / reporting and management data stored in the Airangel cloud.

Base URL

https://MYDOMAIN.admin.captive.net/api/v1

A new API version will be generated for any future changes that are not backward-compatible, at which point endpoints under the old version will be deprecated and eventually revoked.

Requests

Access to any API requires authentication via signed requests generated with an access key and combined with a client id. The signature and client id are added in the HTTP header Authorisation. The Date header should be present in GMT as in the example below.

GET /api/v1 HTTP/1.1 Host: MYDOMAIN.admin.captive.net Date: Wed, 01 Jul 2015 13:48:34 GMT Authorization: Credentials=CLIENT_ID,Signature=2e9659331b79f25d4e8b161…

The signature is calculated using HMAC-SHA256 hashing. The string that needs to be hashed is constructed with the following components and separated by a forward slash:

HTTP Method GET/POST/PUT/DELETE
HOST MYDOMAIN.admin.captive.net
DATE Date included in the HTTP header
Wed, 08 Jul 2015 13:48:34 GMT
PATH api/v1
GET variables Alphabetically ordered by key in the
following format: key=Value;key=value
POST variables Alphabetically ordered by key in the
following format: key=value;key=value

Example:GET/MYDOMAIN.admin.captive.net/Wed, 01 Jul 2015 13:48:34 GMT/api/v1//

''Important: if no GET or POST parameters are passed you still need to include the delimiter (/).''

HTTP Status Codes

  • 200:Successful Request
  • 201:Created
  • 401:Unauthorized
  • 404:Not Found
  • 500:Internal Server Error

Error responses also include a message and (where relevant) a list of failed parameters as an array.

Example error responses including status header:

  • HTTP/1.1 401 Unauthorized
  • Date: Wed, 01 Jul 2015 14:50:52 GMT
  • Content-Length: 40
  • Content-Type: application/json

{
"Code":104,
"message":"invalid request"
}

Local Settings

Each admin (and corresponding API key) has its own locale setting that define how number and dates are formatted. The format of numbers and dates can therefore be different depending on what API key is used.

User/Guest Profiles and related actions

/user

GET

Description Returns a list of all guest profiles available to the API’s client id. By default only profiles active that day are returned unless otherwise defined using the GET parameters below.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user

Optional GET Parameters Search:[activity/creation] #activity is the default

  • From: YYYYMMDD [HHMMSS]
  • to: YYYYMMDD [HHMMSS]
  • offset: integer
  • limit: integer
  • search field: [guest datafield id] (see /datafields)
  • search value: mixed

Example Result

5.1.1 /GET/ Example Results
POST

Description Creates a guest profile (Username / Password).

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user

Required POST Parameters

  • username: #mixed
  • password: #mixed
  • tier: #integer => reference to id tier available via /tier

Optional POST Parameters

  • password: #mixed (optional)
  • First_name #string
  • Last_name #string
  • startdate #date as per locale settings
  • expiration #date as per locale settings
  • bandup #int (bits per second)
  • banddown #int (bits per second)

Example Result

5.1.2 /POST/ Example Results
DELETE

Description Deletes a guest profile based on user id (or username)

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user/[user id]

PUT

Description Updates a voucher / guest profile based on the user id or username

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user/[user id]

Optional POST Parameters

  • username: #mixed
  • password: #mixed
  • tier: #integer => reference to id tier available via /tier
  • First_name #string
  • Last_name #string
  • startdate #date as per locale settings
  • expiration #date as per locale settings
  • bandup #int (bits per second)
  • banddown. #int (bits per second)
5.1.3 /PUT/ Example Results

GET/user/[user id]

Description Returns the detailed object of a user profile - based on the user ID or username

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user/[user id]

Example Result

GET/user/[user id] Example Results

/user/[user id]/sessions

Description Returns a list of all accounting sessions for this user id.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user/[user id]/sessions

Example Result

/user/[user id] Sessions Example Results

/user/[user id]/billing

Description Returns a list of all billing records for this user id.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user/[user id]/billing

Example Result

/user/[user id] Billing Example Results

/user/[user id]/visits

Description Returns a list of all visited tags and the duration for this user id. Tags represent logical location and this data can therefore be used to retrieve location information and perform location analysis.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/user/[user id]/visits

Example Result

File:UserUSERIDvisits.PNG
/user/[user id] Visits Example Results

Sites and Tags

/tag

Description Returns a list of all available tags, tags are logical groups / locations within this domain. Different tag types can be created and one system tag is present, the “Site” tag, a tag that will be set per site/property.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tag

Example Result

6.1/Tags/Example Results

/tag/[tag id]

Description Returns a detailed object for this tag type.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tag/[tag id]

Example Result

/tag/[tag id] Example Results

/tag/[tag id]/values

Description Returns a list of all tags for this tag type. E.g. a list of all sites (for tag type site).

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tag/[tag id]/values

Examples Result

6.3 /Tags/ Values Example Results

/tag/[tag id]/values/[tagvalue id]

Description Returns a detailed object for this tag value.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tag/[tag id]/values/[tagvalue id]

Example Result

6.4 /Tags/ Values Example Results

/tag/[tag id]/values/[tagvalue id]/visits

Description Returns a list of visits to this tag. By default only visits from this day are returned unless otherwise defined using the GET parameters below. You can also get entries for unknown clients, these will include a MAC address of the device but no link to a user profile.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tag/[tag id]/values/[tagvalueid]/visits

Optional GET Parameters

  • from: YYYYMMDD[HHMMSS]
  • to: YYYYMMDD[HHMMSS]
  • offset: integer
  • limit: integer

Example Result

6.5 /Tags/ visits Example Results

Network

/network

Description Returns a list of all network equipment connected to this domain and available to the API key.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/network

Example Result

7.1 /Network/ Equipment Connected Example Results

/network/[network id]

Description Returns a detailed object for this network.

Base URL https://MYDOMAIN.admin.captive.net/api/v1/network/[network id]

Example Result

7.2 /Network/ Report Example Results

Tier

/tier

Description Returns a list of all tiers

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tier

Example Result

8.1 Tier list Example Results

/tier/[tier id]

Description Returns tier object

Base URL https://MYDOMAIN.admin.captive.net/api/v1/tier/[tier id]

Example Result

8.2 Tier Object Example Results

Export

/export

Description Returns all configured exports configured for the admin (identifier) making the call

Base URL https://MYDOMAIN.admin.captive.net/api/v1/export

Example Result

9.1 Return Exports Example Results

/export/[export id]

Description Returns export object

Base URL https://MYDOMAIN.admin.captive.net/api/v1/export/[export id]

Example Result

9.2 Return Export Object Example Results

/export/[export id]/reports

Description Returns all created reports for an export

Base URL https://MYDOMAIN.admin.captive.net/api/v1/export/[export id]/reports

Example Result

9.3 Return created reports Example Results

/export/[export id]/reports/[report id]

Description Returns report data

Base URL https://MYDOMAIN.admin.captive.net/api/v1/export/[export id]/reports

Example Result

9.4 Return Report Data Example Results

Guest Data

Description Returns all guest data fields and their identifier so it can be used for searching the user profiles

Base URL https://MYDOMAIN.admin.captive.net/api/v1/guestdata

Example Result

10 Guest Data Fields Example Results