Navixy Backend API¶

General¶

Each API resource semantically corresponds to some entity, for example: geofences, rules, objects, etc. The API calls for CRUD and other operations with these entities have similar names regardless the resource used: list, read, create, delete.

Standard workflow (example)¶

Let us describe the standard workflow for API developer using very simple and most common example — requesting the track points data:

1. Determine URL to API calls.
2. Obtain hash of an API key
3. Get objects lists with tracker/list.
4. Get track lists with track/list.
5. Get the track itself: track/read.

In other words, to start working with API, the developers should have API call description (as provided herein), and know user login and password.

API base URL¶

Depending on the physical location of the platform it will be:

• https://api.eu.navixy.com/v2 for European Navixy ServerMate platform.
• https://api.us.navixy.com/v2 for American Navixy ServerMate platform.
• https://api.your_domain for the self-hosted (On-Premise) installations.

For example, to make user/auth API call on the European Navixy ServerMate, you should use the URL:

https://api.eu.navixy.com/v2/user/auth

API calls format¶

Notation used in this doc:

/resource/sub_resource/action(parameter1,parameter2,[parameter3])

Which means that you should use the following URL:

[api_base_url]/resource/sub_resource/action

with named parameters:

• parameter1
• parameter2
• parameter3 is optional

Parameters can be passed in the:

• HTTP POST application/json with JSON content, recommended
• HTTP POST application/x-www-form-urlencoded with parameters in the request body
• HTTP GET - not recommended, should be used only for idempotent requests with small parameters size

$ curl -X POST '[api_base_url]/resource/sub_resource/action' \
  -H 'Content-Type: application/json' \
  -d '{"param1": "value1", "hash": "a6aa75587e5c59c32d347da438505fc3"}'

$ curl -X POST '[api_base_url]/resource/sub_resource/action' \
  -d 'param1=value' \
  -d 'hash=a6aa75587e5c59c32d347da438505fc3' 

$ curl '[api_base_url]/resource/sub_resource/action?param1=value1&hash=a6aa75587e5c59c32d347da438505fc3'

Typical actions:

• list – list all resource entities with IDs and minimum additional info
• read – read one entity by ID
• update – update one entity by ID
• delete – delete one entity by ID

Request and response format¶

To make API call, for example, resource/action send POST request to

[api_base_url]/resource/action/

The response will be given with application/json content type, even errors (see error handling). Response fields and object structure is specific to API call.

{
  "success": true,
  "list": [
    {
      "id": 560,
      "label": "GV55",
      "group_id": 12,
      "avatar_file_name": "super-avatar.jpg",
      "source": {
        "id": 2915,
        "model": "gv55lite",
        "blocked": false,
        "tariff_id": 2,
        "phone": "111",
        "status_listing_id": 333,
        "creation_date": "2014-02-02",
        "device_id": "888888888888888"
      },
      "tag_bindings": [
        {
          "tag_id": 1,
          "ordinal": 1
        }
      ],
      "clone": true
    },
    {
      "id": 2799,
      "label": "2799",
      "group_id": 0,
      "source": {
        "id": 2692,
        "model": "m7",
        "blocked": true,
        "tariff_id": 5,
        "phone": null,
        "status_listing_id": null,
        "creation_date": "2006-02-10",
        "device_id": "333333333333333"
      },
      "tag_bindings": [
        {
          "tag_id": 9,
          "ordinal": 3
        }
      ],
      "clone": false
    }
  ]
}

Or error if hash is wrong:

{
  "success": false,
  "status": {
    "code": 4,
    "description": "User or API key not found or session ended"
  }
}

HTTP codes¶

If success is true, HTTP code is always 200 OK (unless otherwise stated). If there is an error, HTTP code is 400 BAD REQUEST (may vary depending on error type) (see error).

Authorization and access levels¶

Unless otherwise noted, every API call requires a valid API Key hash (A string containing 32 hexadecimal characters) that can be passed (in order of lookup priority):

1. As hash parameter of the request body (root-level property for application/json).
2. As hash parameter of the HTTP query string.
3. As value of the HTTP header Authorization in the following form:

Authorization: NVX SessionHashValue

Following is pseudo-grammar that illustrates the construction of the Authorization request header:

Authorization = "NVX" + " " + ApiKeyHashValue ;
ApiKeyValue = 32 hexademical characters;

Read how to get an API key.

Data types¶

• bool, boolean - logical type: true of false.
• byte - signed 8 bits integer in range [-128 .. 128].
• short - signed 16 bits integer in range [-32,768 .. 32,767].
• int, integer - signed 32 bits integer in range [-2,147,483,648 .. 2,147,483,647].
• long - signed 64 bits integer in range [-9,223,372,036,854,775,808 .. 9,223,372,036,854,775,807].
• float - signed 32 bits float number [3.40282347 x 10^38, 1.40239846 x 10^-45].
• double - signed 64 bits float number [1.7976931348623157 x 10^308, 4.9406564584124654 x 10^-324].
• string - string literals.
• enum - string literals from predefined set.
• date/time – is a string containing date/time in defined formats.
• local_time – is a string containing local time in HH:mm:ss format.
• location – is json object contains geographical coordinates, e.g.

  {"lat": 56.827001, "lng": 60.594296}
  

• locale – string in format language[_country], where language is ISO 639 alpha-2 language code, and country is ISO 3166 alpha-2 country code, e.g. en_US or ru. User interface support only language codes: ru, en, es, ar, de, pt, ro and uk.

Date/time formats¶

Date/time type can be represented with formats:

• yyyy-MM-dd HH:mm:ss format (in user's timezone), default
• ISO 8601 yyyy-MM-dd'T'HH:mm:ssZZ

To use ISO 8601 date/time format you should pass true to (in order of lookup priority):

1. iso_datetime parameter of the request body (root-level property for application/json).
2. iso_datetime parameter of the HTTP query string.
3. HTTP header NVX-ISO-DateTime

$ curl -X POST '[api_base_url]/resource/sub_resource/action' \
-H 'Content-Type: application/json' \
-d '{"iso_datetime": true, "hash": "a6aa75587e5c59c32d347da438505fc3"}'

$ curl -X POST '[api_base_url]/resource/sub_resource/action' \
-d 'iso_datetime=true' \
-d 'hash=a6aa75587e5c59c32d347da438505fc3'

$ curl -X POST '[api_base_url]/resource/sub_resource/action' \
-H 'Content-Type: application/json' \
-H 'NVX-ISO-DateTime: true' \
-d '{"hash": "a6aa75587e5c59c32d347da438505fc3"}'

response example with fixed offset date/time :

{
  "success": true,
  "user_time": "2014-07-09T07:50:58+05:00",
  "list": [
    {
      "type": "odometer",
      "value": 100500.1,
      "update_time": "2014-03-06T13:57:00+05:00"
    }
  ]
}

response example with UTC date/time :

{
  "success": true,
  "user_time": "2014-07-09T02:50:58Z",
  "list": [
    {
      "type": "odometer",
      "value": 100500.1,
      "update_time": "2014-03-06T17:57:00Z"
    }
  ]
}

Error handling¶

If an error occurs, API returns special error response. You can also detect error by checking HTTP response code. If it is not 200 OK, you should parse and handle response body as an error response. In the event of error occurs, the response will be in the following format:

{
  "success": false,
  "status": {
    "code": 1,
    "description": "Database error"
  }
}

Error codes¶

Default HTTP code is 400. Common error codes (should be handled for all API calls) are 1-100 and resource or action specific errors are 101-300.