API usage information

Authentication

Connection to the API is provided via HTTPS. Authentication is done using the user's credentials and the token that is provided after authorization. We advise that the token property that is received during authorization be used for any subsequent request.

Request responses and handling

All the responses from the interface will be in the form of JSON. The responses will contain one of the following keys which are described below:

Success response

A successful response will contain a json response with a success key. An example of a succesful request is shown below:

    {
        "success": "You have been Spoiled"
    }

The key "success" can be used to validate the response and each endpoint will however contain information specific to it and this can be verified on the endpoint's page.

Failed response

A failed response will contain a json response with a failed key. An example of a failed request is shown below:

    {
        "failed": "Incorrect username/password!"
    }

The key "success" can be used to validate the response and each endpoint will however contain information specific to it and this can be verified on the endpoint's page.

Detail response

In some cases, if the failure of the request is due to incorrect data type, the response can be handled using the detail key. A detail response will contain a json response with a detail key. An example of a failed request is shown below:

{
    "detail": [
        {
            "loc": [
                "body",
                "sensor_value"
            ],
            "msg": "value is not a valid float",
            "type": "type_error.float"
        }
    ]
}

The key "detail" can be used to validate the response and each response will however contain information specific to it. For example, in the response above, the value for paramer sensor_value is not a valid float and hence the request failed.

Update delay

Interface updates are limited by a delay and this is related to the user's account type. E.g. If the user uses a free account, the update interval is made to be 60s. If you try updating the interface before the time lapses, the following failed response will be given. The remaining_time_sec variable can be used to wait for the time to lapse.

{
    "failed": {
        "message": "Please wait for the update period to lapse. Remaining time is: 29",
        "remaining_time_sec": 29
    }
}