B2Field 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's describe standard workflow for API developer using very simple and most common example — requesting the track points data:

1. Determine URL to API calls.
2. Authorize with user/auth. This API method will return the hash you should use for all your next API calls.
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/fsm for European B2Field ServerMate platform.
• https://api.us.navixy.com/v2/fsm for American B2Field ServerMate platform.
• https://api.your_domain/fsm for the self-hosted (On-Premise) installations.

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

https://api.eu.navixy.com/v2/fsm/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 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 user session hash (A String containing 32 hexademical 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 pseudogrammar that illustrates the construction of the Authorization request header:

   Authorization = "NVX" + " " + SessionHashValue ;
   SessionHashValue = 32 hexademical characters;
   

Session hash can be obtained via user/auth API call:

$ curl -X POST '[api_base_url]/user/auth' \
       -H 'Content-Type: application/json' \ 
       -d '{"login": "demo", "password": "demo"}'

[api_base_url]/user/auth?login=demo&password=demo

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 yyyy-MM-dd HH:mm:ss format (in user's timezone).
• 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.

Constants¶

• maxHistoryLimit = 1000 – maximum count of history entries from listing requests
• maxReportTimeSpan = 120 days – maximum interval in for most requests

Error handling¶

If an error occurs, API returns special error response. You can also detect error by checking HTTP response code. If it's 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.