API Overview

The EdgeIQ API is designed to make it easy for developers to create applications using a REST API to represent connected things and other, aggregated APIs. As with all REST APIs, each request is atomic - there is no session.

Resources

Request signatures generally follow a resource-based convention:

• List: GET /resource
• Retrieve: GET /resource/{id}
• Create: POST /resource
• Update: PUT /resource/{id}
• Destroy: DELETE /resource/{id}

All of the individual resources and their associated REST endpoints are documented under the section labeled API Docs.

API Token

You need an API token to use the EdgeIQ APIs. Your account has two different kinds of tokens: the permanent token that is generated when the profile is created, and the temporary token that is created during authentication. If your administrator did not give you your permanent token, you can use the Portal to reset that token by managing your profile, (in the top right), and clicking the "Reset API Token" button. This will provide you with a newly generated permanent token for your account. If you'd like to issue the request instead of using the Portal, refer to the request below.

URL:

POST https://api.edgeiq.io/api/v1/platform/user/api_token_reset

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Your permanent API token will be found in the api_token field of the response body.

Getting a temporary token is possible by issuing a POST request to user/authenticate, as outlined below. The token_expiry field is optional; if omitted the token will expire in 4 hours. The value of token_expiry must be a UTC datetime no greater than a week in the future.

URL:

POST https://api.edgeiq.io/api/v1/platform/user/authenticate

Headers:

Accept: application/json
Content-Type: application/json

Body:

{
  "email": "[email protected]",
  "password": "yourpassword",
  "token_expiry": "2019-06-10T19:49:51.217Z"
}

The response body's JSON will contain your profile's information, including your temporary API token that can be found in the session_token field. This token's expiration can be found in the session_expires_at field.

Now that you have your permanent or temporary API token you can set the Authorization header of your requests and begin using the EdgeIQ API.

Request Headers

All EdgeIQ APIs consume and produce JSON (application/json MIME type). Nearly all APIs also require user authentication (Basic auth — see below). The following header rules therefore apply:

1. All requests must include:

Accept: application/json

2. Requests with a body (e.g., POST, PUT) must also include:

   Content-Type: application/json

3. Endpoints requiring authentication (all except user authenticate and device report POST endpoints) must also include:

   Authorization: <your API token>

The Authorization header can also be automatically generated for each request when using the "Try it out" feature within the developer portal.

Query String Operators

All GET requests to the EdgeIQ API have the ability to query specific fields on the underlying data. For example, if you're looking for a specific device type, you could make a request that looks something like:

GET .../device_types?manufacturer=Acme&model=Dynamite1000

You also have the ability to use basic logical operators on the query string. For example, if you wanted to look for all devices created since the first of March 2015, you could do something like this:

GET .../devices?created_at_gt=2018-03-01

All logical operators are appended to the field on which they are being applied. Keep in mind that the query string will only look at the last occurrence of a key pair when a key appears more than once. For the case that you need a values between two thresholds, we've included the _between operator that takes two arguments separated by an underscore. Below is a list of basic operators.

Paging

All GET requests that return multiple results are paged. Paging defaults to 20 per page. If you wish to retrieve pages beyond the first page or have more results returned per page, you can use the query string parameters page and per_page like this:

GET .../devices?page=2&per_page=50

The default behavior of requests that return a list is to return a JSON array of objects at the top level. Sometimes it's helpful to know more about the big picture when it comes to paging...How many pages are there? How many total resources are there? This can be achieved using the page_meta query string parameter. When set to true a JSON object, rather than an array, will be returned. The object will contain several keys indicating paging metadata and an array call resources that would be the normal default return.

GET .../devices?page_meta=true

Returns:

{
  "page": 1,
  "per_page": 20,
  "total": 26,
  "resources": [
    { ... },
    { ... },
   ...
  ]
}

In

All GET requests have the ability to use the query parameter in. The in query parameter behaves similarly to the IN SQL operator. When using the in query parameter, the requester must distinguish which field in the resource that the requester would like to search. The requester can then separate multiple input values with a comma. For example:

GET .../device_types?make_in=samsung,sony,lq

Returns all records that have a make of samsung sony or lg

Sorting

All GET requests that return multiple results may be ordered by a field. Results are typically returned in the order they persisted: oldest first. Reports are returned the newest first. To change the order of the results, you can use the query string parameter order_by:

GET .../devices?order_by=name

That will return an array of objects sorted by the name field in ascending order. To sort in descending order, negate the field name like below:

GET .../devices?order_by=-name

You may order by any field on the document but please note that not all fields are indexed in the database. So some fields may cause the response to take longer than others.