Proximity Kit Admin API

This document describes the API designed to integrate Proximity Kit with other systems. It is specifically intended to manage creation and deletion of kits, regions, the associated meta data.

Data synchronization, communicating with the SDKs, configuring hardware is not part of the Admin API. Radius Networks has other resources for many of those needs.

Overview

This API uses IDs for linkage, which makes it possible to cache documents from compound responses and then limit subsequent requests to only the documents that aren't already present locally.

Resource relationships are created through the use of URI templates and resource identifiers. To prevent future breakage we recommend creating the URIs from the templates over hardcoding to the individual resources.

Headers

Authorization

The API Key is passed via the Authorization header:

Authorization: Token token="secret"

The API Key is associated with your account and has access to all the resources associated with your account. Account-specific API keys have different permissions than the web login users that can interact with the dashboard, and the access may be different.

Example:

curl -H 'Authorization: Token token="sandbox"' "https://proximitykit.radiusnetworks.com/api/v1.json"

API Tokens can be managed in your Radius Networks Account Profile.

Note: Per RFC 2616 the Authorization Header's token needs to be surrounded by double quotes (").

Content Type

The content type is vnd+json, and should be set in the Content-Type header:

Content-Type: application/vnd.api+json

API Root

GET /api/v1

The list of links for the resources available to your account.

Root Document:

GET /api/v1

{
  "version": "1.0",
  "links": {
    "users.kits": "https://proximitykit.radiusnetworks.com/api/v1/kits/{users.kits}"
  },
  "users": [
    {
      "id": 3,
      "links": {
        "kits": [52,53]
      }
    }
  ]
}

Key	Value
`version`	The media type version
`links[users.kits]`	The url template for a kit resource
`users[links][kits]`	List of kit IDs that belong to a user

Curl Example:

% curl -s \
       -X GET \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1

Kits

Kit Resource

GET /api/v1/kits/:id

Return the kit resource, describing the attributes and related beacons.

{
  "version": "1.0",
  "links": {
    "kits.beacons": "https://proximitykit.radiusnetworks.com/api/v1/beacons/{kits.beacons}",
    "kits.circle_overlays": "https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/{kits.circle_overlays}"
  },
  "kits": [
    {
      "name": "Ancient Rome",
      "id": 52,
      "links": {
        "beacons": [2,3,4,5],
        "circle_overlays": [3,4,5,6]
      }
    }
  ]
}

Key	Value
`version`	The media type version
`links[kits.beacons]`	The url template for an beacon resource
`links[kits.circle_overlays]`	The url template for a geofence circle overlay resource
`kits[links][beacons]`	List of kit IDs that belong to a user

Curl Example:

% curl -s \
       -X GET \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/kits/52

Listing Kits

GET /api/v1/kits/:id

Return a paginated of kit resources.

{
  "version": "1.0",
  "meta": {
    "current": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=3",
    "next": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=4",
    "previous": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=2",
    "first": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=1",
    "last": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=10"
  },
  "links": {
    "kits.beacons": "https://proximitykit.radiusnetworks.com/api/v1/beacons/{kits.beacons}"
  },
  "kits": [
    {
      "name": "Ancient Rome",
      "id": 52,
      "links": {
        "beacons": [ 2, 3, 4, 5 ]
      }
    },
    //...
  ]
}

Key	Value
`version`	The media type version
`links[kits.beacons]`	The url template for an beacon resource
`kits[links][beacons]`	List of kit IDs that belong to a user
`meta[next]`	URI of the next page of results
`meta[previous]`	URI of the previous page of results
`meta[first]`	URI of the first page of results
`meta[last]`	URI of the last page of results

Creating a Kit

To create a kit make a post request to the /api/v1/kits

POST /api/v1/kits

The response will include the JSON representation of the newly created kit as well as a Location header with the URI of the resource.

Example:

{"kits": [{ "name": "My New Name" }] }

Required Parameters:

Parameter	Description
name	The name of the kit

Curl Example:

% curl -sv \
       -X POST \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       -d ' {"kits":[{ "name": "My Name" }]}'
       https://proximitykit.radiusnetworks.com/api/v1/kits
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/kits/56
< Content-Type: application/vnd.api+json; charset=utf-8
{
  "kits": [
    {
      "name": "My Name",
      "id": 56,
      "links": { "beacons": [] }
    }
  ]
}

Updating a Kit

To update a kit make a put request to the /api/v1/kits.

PUT /api/v1/kit/:id

Example:

{"kits": [{ "name": "My New Name" }] }

Parameters:

Parameter	Description
`name`	The name of the kit

Curl Example:

% curl -sv \
       -X PUT \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       -d ' {"kits":[{ "name": "Silly Name" }]}' \
       https://proximitykit.radiusnetworks.com/api/v1/kits/56
< HTTP/1.1 204 No Content

Deleting a Kit

To delete a kit make a delete request to the individual kit url.

DELETE /api/v1/kit/:id

The response be 201 No Content if the delete was successful.

Curl Example:

% curl -sv \
       -X DELETE \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json"
       https://proximitykit.radiusnetworks.com/api/v1/kits/56
< HTTP/1.1 204 No Content

Beacons

Beacon Resource

GET /api/v1/beacons/:id

This will return an beacon resource.

{
  "links": {
    "beacons.attributes": "https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/{beacons.attributes}"
  },
  "beacons": [
    {
      "id": 6,
      "name": "Earth",
      "uuid": "E58171D9-8398-4453-A991-5593682DDB56",
      "major": 1000,
      "minor": 1,
      "links": {
        "attributes": [3,4]
      }
    }
  ]
}

Key	Value
`version`	The media type version
`links[beacons.attributes]`	The url template for a beacon attribute resource
`beacons[name]`	Display name for the beacon
`beacons[uuid]`	Orgnization level proximity identifier
`beacons[major]`	Group level proximity identifier
`beacons[minor]`	Physical beacon proximity identifier
`beacons[links][attributes]`	List of attribute IDs that belong to the beacon

Curl Example:

% curl -s \
       -X GET \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/beacons/6

Creating a beacon

To create a beacon make a POST request to the /api/v1/beacons

Parameters

Parameter	Description
`kit_id`	The ID of the associated kit	Required
`uuid`	The beacon UUID	Required
`name`	The name of the beacon
`major`	The major beacon identifier
`minor`	The minor beacon identifier

POST /api/v1/beacons

The response will include the JSON representation of the newly created kit as well as a Location header with the URI of the resource.

Example:

{
  "links": {
    "beacons.attributes": "https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/{beacons.attributes}"
  },
  "beacons": [
    {
      "id": 6,
      "name": "Earth",
      "uuid": "E58171D9-8398-4453-A991-5593682DDB56",
      "major": 1000,
      "minor": 1,
      "links": {
        "attributes": []
      }
    }
  ]
}

Curl Example:

% curl -sv \
     -X POST \
     -H 'Authorization: Token token="secret"' \
     -H "Content-Type: application/vnd.api+json" \
     -d '{"beacons": [{"kit_id":52, "name": "Earth 2", "uuid": "E58171D9-8398-4453-A991-5593682DDB56", "major": 1002, "minor": 1}]}' \
     https://proximitykit.radiusnetworks.com/api/v1/beacons
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/beacons/7

Updating an beacon

To update a beacon make a put request /api/v1/beacons/:id

Parameters

Parameter	Description
`kit_id`	The ID of the associated kit	Required
`uuid`	The beacon UUID
`name`	The name of the beacon
`major`	The major beacon identifier
`minor`	The minor beacon identifier

PUT /api/v1/beacon/{beacon_id}

Example:

{
  "beacons": [
    {
      "kit_id": 1,
      "name": "My New Name",
      "uuid": "d16eae19-6fce-4198-a5a5-469c9599b709",
      "major": 1,
      "minor": 1
    }
  ]
}

Deleting a Beacon

To delete a beacon make a delete request to api/v1/beacon/:id.

DELETE /api/v1/beacon/:id

Curl Example:

% curl -sv \
       -X DELETE \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/beacons/7
< HTTP/1.1 204 No Content

Beacon Attributes

Beacon Attributes Resource

GET /api/v1/beacon_attributes/:id

This will return a list of beacon attributes.

{
  "beacon_attributes": [
    {
      "id": 4,
      "key": "population",
      "value": "eleventy billion"
    }
  ]
}

Curl Example:

% curl -s \
       -X GET \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/4

Creating an attribute

To create an attribute make a post request to api/v1/beacon_attributes

Parameters

Parameter	Description
`beacon_id`	The ID of the associated beacon	Required
`key`	The key value
`value`	The data associated with the key

POST /api/v1/beacon_attributes

Example:

{
  "beacon_attributes": [
    {
      "beacon_id": 5,
      "key": "venue",
      "value": "spaceship"
    }
  ]
}

% curl -sv \
       -X POST \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       -d '{ "beacon_attributes": [ { "beacon_id": 5, "key": "venue", "value": "spaceship" } ]}' \
       https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/5.5

Updating an attribute

To update an attribute make a post request to api/v1/beacon_attributes/:id.

Parameters

Parameter	Description
`key`	The key value	Required
`value`	The data associated with the key	Required
`beacon_id`	The ID of the parent beacon

PUT /api/v1/beacon_attributes/:id

Example:

{
  "beacon_attributes": [
    {
      "key": "venue",
      "value": "spaceship with dinosaurs"
    }
  ]
}

Curl Example:

% curl -sv \
       -X PUT \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       -d '{ "beacon_attributes": [ { "key": "venue", "value": "spaceship with dinosaurs" } ]}' \
       https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/5
< HTTP/1.1 204 No Content

Deleting an attribute

To delete an attribute make a delete request to the individual beacon_attribute_url.

DELETE /api/v1/beacon_attributes/:id

Curl Example:

% curl -sv \
       -X DELETE \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/4
< HTTP/1.1 204 No Content

Circle Overlays

Circle Overlay Resource

GET /api/v1/circle_overlays/:id

This will return a circle overlay resource.

{
   "circle_overlays" : [
      {
         "id" : 7,
         "name" : "Headquarters",
         "radius" : 80.704567,
         "links" : {
            "kit" : 4,
            "attributes" : [],
            "self" : "https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/760"
         },
         "center_longitude" : -77.066093,
         "center_latitude" : 38.904539
      }
   ],
   "links" : {
      "circle_overlays.kit" : "https://proximitykit.radiusnetworks.com/api/v1/kits/{circle_overlays.kit}",
      "circle_overlays.attributes" : "https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/{circle_overlays.attributes}"
   }
}

Key	Value
`version`	The media type version
`links[circle_overlays.attributes]`	The url template for a circle overlay attribute resource
`circle_overlays[name]`	Display name for the circle overlay
`circle_overlays[radius]`	Radius of the geofence in meters
`circle_overlays[center_longitude]`	longitude of the center point
`circle_overlays[center_latitude]`	latitude of the center point
`circle_overlays[links][attributes]`	List of attribute IDs that belong to the circle overlay

Curl Example:

% curl -s \
       -X GET \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/6

Creating a Circle Overlay

To create a circle overlay make a POST request to the /api/v1/circle_overlays

Parameters

Parameter	Description
`kit_id`	The ID of the associated kit	Required
`name`	Display name for the circle overlay
`radius`	Radius of the geofence in meters	required
`center_longitude`	longitude of the center point	required
`center_latitude`	latitude of the center point	required

POST /api/v1/circle_overlays

The response will include the JSON representation of the newly created kit as well as a Location header with the URI of the resource.

Example:

{
  "circle_overlays": [
    {
      "kit_id": 6,
      "name" : "Headquarters",
      "radius" : 80.704567,
      "center_longitude" : -77.066093,
      "center_latitude" : 38.904539
    }
  ]
}

Curl Example:

% curl -sv \
     -X POST \
     -H 'Authorization: Token token="secret"' \
     -H "Content-Type: application/vnd.api+json" \
     -d '{"circle_overlays": [{"kit_id":52, "name" : "Headquarters", "radius" : 80.704567, "center_longitude" : -77.066093, "center_latitude" : 38.904539 }]}' \
     https://proximitykit.radiusnetworks.com/api/v1/circle_overlays
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/7

Updating a Circle Overlay

To update a circle overlay make a put request /api/v1/circle_overlays/:id

Parameters

Parameter	Description
`kit_id`	The ID of the associated kit	Required
`name`	Display name for the circle overlay
`radius`	Radius of the geofence in meters	required
`center_longitude`	longitude of the center point	required
`center_latitude`	latitude of the center point	required

PUT /api/v1/circle_overlay/{circle_overlay_id}

Example:

{
  "circle_overlays": [
    {
      "kit_id": 1,
      "name" : "Headquarters",
      "radius" : 80.704567,
      "center_longitude" : -77.066093,
      "center_latitude" : 38.904539
    }
  ]
}

Deleting a Circle Overlay

To delete a circle overlay make a delete request to api/v1/circle_overlays/:id.

DELETE /api/v1/circle_overlays/:id

Curl Example:

% curl -sv \
       -X DELETE \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/7
< HTTP/1.1 204 No Content

Circle Overlay Attributes

Circle Overlay Attributes Resource

GET /api/v1/circle_overlay_attributes/:id

This will return a list of circle overlay attributes.

{
  "circle_overlay_attributes": [
    {
      "id": 4,
      "key": "population",
      "value": "eleventy billion"
    }
  ]
}

Curl Example:

% curl -s \
       -X GET \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/4

Creating an attribute

To create an attribute make a post request to api/v1/circle_overlay_attributes

Parameters

Parameter	Description
`circle_overlay_id`	The ID of the associated circle overlay	Required
`key`	The key value
`value`	The data associated with the key

POST /api/v1/circle_overlay_attributes

Example:

{
  "circle_overlay_attributes": [
    {
      "circle_overlay_id": 5,
      "key": "venue",
      "value": "spaceship"
    }
  ]
}

% curl -sv \
       -X POST \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       -d '{ "circle_overlay_attributes": [ { "circle_overlay_id": 5, "key": "venue", "value": "spaceship" } ]}' \
       https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/5.5

Updating an attribute

To update an attribute make a post request to api/v1/circle_overlay_attributes/:id.

Parameters

Parameter	Description
`key`	The key value	Required
`value`	The data associated with the key	Required
`circle_overlay_id`	The ID of the parent circle overlay

PUT /api/v1/circle_overlay_attributes/:id

Example:

{
  "circle_overlay_attributes": [
    {
      "key": "venue",
      "value": "swimming pool room"
    }
  ]
}

Curl Example:

% curl -sv \
       -X PUT \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       -d '{ "circle_overlay_attributes": [ { "key": "venue", "value": "swiming pool room" } ]}' \
       https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/5
< HTTP/1.1 204 No Content

Deleting an attribute

To delete an attribute make a delete request to the individual circle_overlay_attribute_url.

DELETE /api/v1/circle_overlay_attributes/:id

Curl Example:

% curl -sv \
       -X DELETE \
       -H 'Authorization: Token token="secret"' \
       -H "Content-Type: application/vnd.api+json" \
       https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/4
< HTTP/1.1 204 No Content