REST APIs

Overview

EDGEHOG Device Management APIs allow you to create and manage content on the EDGEHOG platform to manage your fleet of devices also from your company application. The main features accessible from the Web Control Panel are available through Public APIs such as Models creation, Devices creation, update campaigns, etc.

This documentation will help developers who want to integrate EDGEHOG services inside their workflow.

EDGEHOG API is organized around REST and uses HTTP verbs and response codes that most clients are familiar with.

All requests should be made over HTTPS. Our communication standard is JSON, both for successful and error responses.

The Endpoint to reach or call our API library is: https://edgehog.cloud/api/v1

Security

We take security VERY seriously!

EDGEHOG API uses the Resource Owner Password Credentials Grant flow of OAuth 2.0 for authentication and allows applications to submit authenticated requests on behalf of individual EDGEHOG users using the access credentials. In exchange for valid credentials will be returned an access token in the JSON Web Token (JWT) format.

Once received the valid access token, you simply need to include it with all of your EDGEHOG requests in the authorization header as follows:

Authorization: Bearer <jwt.token>

The bearer token is your key to accessing all of your resources via EDGEHOG API. Keep it safe.

TLS must be used in all EDGEHOG API interactions, calls made without TLS will be rejected. Requests made without authentication will also be rejected.

Limitation and Suggestions

  • Tokens generated with APIs, are associated with the single EDGEHOG account and they inherit the privileges they are associated with.

  • Tokens MUST be generated in a secure/safe environment. We HIGHLY discourage the creation of tokens within your front end. Violation of this recommendation could result in the temporary suspension of the service.

  • Secret keys must never be made public.

  • Our systems limit the requests to a maximum of 60 requests every minute, coming from the same authenticated user or the same IP/domain. The response header contains the limit, the remaining available requests, and the time in which the counter resets (in seconds).

  • Each token is valid for a fixed time (1 hour), for security reasons. After this expiration time, the system will automatically revoke the token making it invalid. To generate a new token can be used the refresh API (using the old one) or the login API using credentials

Request Methods

Method

Description

GET

A request of one or multiple elements

POST

Create an element

PUT

Modify or action on an element

DELETE

Delete an element

HTTP Status codes

All responses/errors are returned in the form of JSON with a type and optional message.

Success codes

Code

Description

200

Success - Request successfully completed

201

Created - Request successfully created (POST calls)

204

Success - No Content

Request Error codes

Error Code

HTTP Status

Error

1000

400

Record not found

1100

400

Invalid filter

2000

400

Unique constraint violated

2100

422

Invalid input

2200

415

Invalid image

2201

415

Invalid file

2300

409

Possible stale data

2400

400

Invalid request

2500

400

Invalid argument

Authorization errors codes

Error Code

HTTP Status

Error

3000

401

Invalid credentials

3100

400

User account exception

3200

400

User group exception

3300

403

Missing privilege

3400

422

Security lock exception

3500

400

JWT exception

3600

429

User's account is locked

3700

403

Authorization exception

Server errors codes

Error Code

HTTP Status

Error

4100

500

Missing certificate

4200

500

Invalid provider

5100

500

External API exception

5200

500

External API timeout

5300

500

IoT broker exception

9999

503

Maintenance mode enabled

Documentation

For sharing the EDGEHOG API documentation we have chosen to use the Swagger Hub platform, which allows the developer to have all the necessary tools to set up his code quickly through examples and ready-made parts of code. For example, you can export, from the swagger description file we provide, ready-made clients in some languages, or test stub servers. Otherwise, you can only View Documentation of the APIs in a more readable way, using the appropriate button on the page.

Our APIs are divided into different macro-areas environments Authentication, Production, and Management.

Authentication APIs

Here are described the API calls needed for authentication, requesting/refreshing the JWT token, as described in the Security section above.

See the Swagger format documentation at this link:

https://app.swaggerhub.com/apis/edgehog-iot/Authentication/v1

Production APIs

Here are described the API calls necessary to automate the production process at your company, before sending the complete devices to the field.

See the Swagger format documentation at this link:

https://app.swaggerhub.com/apis/edgehog-iot/Production/v1

Management APIs

Here are described the API calls needed for manage EDGEHOG device already created and available on the field, then all the operations related to the device life cycle (decommissioning, replace gw, reinstall os) and all the OS update campaigns or campaigns related to Docker Applications or Files.

See the Swagger format documentation at this link:

https://app.swaggerhub.com/apis/edgehog-iot/Management/v1