Skip to content

Latest commit

 

History

History
104 lines (87 loc) · 3.57 KB

README.md

File metadata and controls

104 lines (87 loc) · 3.57 KB
Raw

Hiber Rest API

This is the specification for the Hiber Rest API.

The Rest API is intended for read-only funcationality only. Anything more complicated is handled by the Hiber GRPC API.

Usage

Use any http client that supports setting (auth) headers, like, curl, Postman, etc.

Auth

To authenticate when using the API, you will need:

  • A token for the organizations you wish to use the Rest API for. (Impersonation is not currently supported)
    • Go to Developer Tools / Tokens in Mission Control
    • Make a new token with the permissions you need, typically modems and messages.
    • Copy the token string.
  • When doing a request on the API, add the Authentication header with the value Bearer <your-token>, where <your-token> is the token copied above.

HAL

We've added some additional information to API responses using the _links field, following the HAL specification.

For example, each response will contain a field at _links.self.href that links back to the current page, or, when requesting a list (i.e. messages or message-events), it will contain _links.next.href for the next page.

The _links also contains some simple specifications of available commands and documentation, defined using a CURIE under _links.curies and using URI Templates like messages{?from,to,devices,tags,groups,size,page}.

Endpoints

The currently available endpoints are:

Simple example

For example:

$ curl -v https://rest.hiber.cloud/modem/ABCD0123 -H "Authorization: Bearer <token>"
{
    "modem": {
        "organization": "hiber",
        "number": "ABCD 0123",
        "name": "ABCD 0123",
        "identifier": "00 00 00 00 00 00 00 00",
        "location": {
            "latitude": 1.2345,
            "longitude": 1.2345,
            "textual": "[1.2345,1.2345]"
        },
        "healthLevel": {
            "level": "Warning",
            "color": "#FFD67A",
            "colorData": {
                "fill": "#FFD67A",
                "markerBackground": "#EDB63C",
                "markerForeground": "#FFFFFF",
                "text": "#FFD67A"
            },
            "severity": "2"
        },
        "notes": "My important device",
        "tags": [
            {
                "id": "3",
                "label": {
                    "name": "my group",
                    "type": "group"
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://rest.api.dev.env.hiber.cloud/modem/0E2C05C1"
        },
        "hiber:messages": {
            "href": "https://rest.api.dev.env.hiber.cloud/messages{?from,to,modems,devices,tags,groups,size,page}",
            "templated": true
        },
        "hiber:message-events": {
            "href": "https://rest.api.dev.env.hiber.cloud/message/events{?from,to,modems,devices,tags,groups,size,page}",
            "templated": true
        },
        "curies": [
            {
                "href": "https://rest.api.dev.env.hiber.cloud/docs/rels/{rel}",
                "name": "hiber",
                "templated": true
            }
        ]
    }
}