The Vicotee API is organized around REST. Our API returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Most applications will use an existing wrapper library in the language of your choice, but it's important to familiarize yourself with the underlying API HTTP methods.
For this purpose, we will use cURL. If you are using an alternative client, note that you are required to send a valid User Agent header in your request. All API requests must be made over HTTPS.
NOTE: the cURL in all examples are written for Linux cURL. If you are using Windows, some changes may be required for the examples to work, especially the backslash for “new line” won't work for Window.
Open up a command prompt and enter following command:
$ curl https://cloud.vicotee.com/api/demo/hello
> Hello there…The response is “Hello there…”
Next, let's a demo IoT device:
$ curl https://cloud.vicotee.com/api/demo/device
> {
> "id": "1234567890",
> "uuid": "1234560000000001",
> "name": "Meeting room 'orange'",
> "description": "This is a demo",
> "sn": "220190364",
> "pn": "1101144"
> }The response is a JSON object.
Let's call the same request, this time we add -i flag to include the headers:
$ curl https://cloud.vicotee.com/api/demo/device
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 06:28:06 GMT
> {
> "id": "1234567890",
> "uuid": "1234560000000001",
> "name": "Meeting room 'orange'",
> "description": "This is a demo",
> "sn": "220190364",
> "pn": "1101144"
> }The response headers return Content-Type of application/json.
Any headers beginning with X- are custom headers, and are not included in the HTTP spec.
Some API requests require parameters. Parameters are passed as part of the request endpoint (URI).
Syntax: key=values
Let's get the demo IoT device, this time we send with the field parameter with name and description as values.
$ curl https://cloud.vicotee.com/api/demo/device?fields=name,description
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 06:28:06 GMT
> {
> "id": "1234567890",
> "name": "Meeting room 'orange'",
> "description": "This is a demo"
> }The response JSON object contains only the fields id, name, and description. The field ID is mandatory, and most JSON objects contain an ID, so it is not necessary to have an ID in the field parameter. You can read about this special ‘fields’ parameter.
Most IDs returned from Vicotee's server are string data types, even they are a number. If you use a strong type language, you may want to convert them to a long data type.
The Vicotee API requires minimum one header, that will be Content-Type set as application/json. Let's get the demo device again, this time with Content-Type in the header:
$ curl -i https://cloud.vicotee.com/api/demo/device -H "Content-Type: application/json"
> HTTP/1.1 200 OK
> Connection: keep-alive
> Vary: Accept-Encoding
> Transfer-Encoding: chunked
> Content-Type: application/json
> X-Application-Context: gateway-zuul:dev:8000
> Date: Wed, 25 May 2022 13:52:50 GMT
>
> {
> "id": "1234567890",
> "uuid": "1234560000000001",
> "name": "Meeting room 'orange'",
> "description": "This is a demo",
> "sn": "220190364",
> "pn": "1101144"
> }Every API requests, with a few exceptions, needs Authorization header. The value to set for this header is the API token you have acquired through Authentication API. You can read more about this at Authentication.
The Vicotee's API is based on REST, and it support following HTTP request methods: GET, POST and DELETE. You will not see any API using PUT.
REST specification suggest that GET is used for retrieving data, POST is for creating data, while DELETE is for deleting data and PUT is for updating data. However, data entities in Vicotee's servers are identified with an ID attribute. When creating new data entity using POST, and the ID attribute is undefined, the server will therefor treat it as new entity. If ID attribute exists on your POST request object, then the server will perform an update.
Not all fields are visible when they do not have values (ie. they are either undefined or null). Example, if a device doesn't have a description you can expect the response object to be like this (where description field is omitted):
{
"id": "1234567890",
"uuid: "75403000000",
"name": "Demo"
}Here is how response object will look like if description field has a value:
{
"id": "1234567890",
"uuid: "75403000000",
"name": "Demo",
"description": "Mounted far left of the meeting room"
}
Most of the response data entity will have an id, a unique identification of the entity. Another common field is iTimestamp, it's the timestamp for “last modified”.
In some cases, a data entity may have uuid or a serial number (sn) as identifications; device object is typically a object that contains all three identifications. Which identifications you need to use depends on APIs, some APIs require uuid, some require id.