Query and response types

Query parameters (GET and POST data)

Optional[main_type] (null)

Marks that parameter is optional. Note that null (no parameter passed) is not the same as passing empty string or 0 symbol param. Empty string is considered as string type, 0 is integer type (or boolean false value).
Empty string example: https://api.carrotquest.io/users/123?param=.
Query with null (no parameter param at all): https://api.carrotquest.io/users/123.

ID

Object identifier. Unsigned integer number. Minimal value is 1. Maximum value is - 2^64 - 1 (2 to the power of 64).
Important! There can be problems with 64-bit numbers interpretation in browser.

Boolean

Boolean values can be passed in different ways:

• If parameter is not passed (and has no default value), it has null value and is interpreted depending on request.
• Any form of false word is interpreted is false value. For instance: False, false, FALSE, FalsE
• Character 0, or empty string '' are interpreted as false value.
• Any other word is interpreted as true value.

Timestamp

Time in seconds since 1970/01/01 UTC. Can be set as integer or float-pint number (divided by . character). Example: param=1684923942.123456

Arrays and objects (dictionaries, dict)

Arrays and objects must be JSON-encoded before passing to query (use JSON.stringify() or its analogs).
Array example: param=["a", "b", "c"].
Object example: param={"a":123,"b":"c"} Single-dimension arrays, containing string or numbers can be passed in "over-comma" style.
For example, param=1,2,3 or param=a,b,c.

Response formats

ID

Many Dashly objects have 64-bit integer primary key. JavaScript language (and some others) have limited support of 64-bit numbers and corrupt them. In order to make it work fine and prevent errors Web API can return all primary keys as strings. This is implemented as special boolean parameter (GET or POST) id_as_string which can be passed to all API queries.

Important! In order to keep API back compatible, by default API returns primary keys as numbers and browser parses them incorrectly.

Examples:

GET https://api.dashly.app/users/{id}

{
  "meta": {
    "status": 200
  },
  "data": {
    "id": 1448121617782670208,
    "app": 100,
    "user_id": null,
    "presence": "idle",
    "removed": null
  }
}

GET /users/{id}?id_as_string=true

{
  "meta": {
    "status": 200
  },
  "data": {
    "id": "1448121617782670208",
    "app": "100",
    "user_id": null,
    "presence": "idle",
    "removed": null
  }
}

Datetime, timestamp

Datetime can be returned in 2 ways:
* timestamp. Can be an integer or float (with microseconds) number. * a string as specified in the standard ISO 8601.