Extended JSON

JSON has a well-defined structure for basic structures like objects and arrays, as well as primitive types like strings and numbers. Additional structures can be achieved using special operators.

Prerequisite to test following examples is to have an API key with permissions:

Path	Methods	ACL
/resources/transaction	POST	off

Date

Storing data as a date structure can be achieved using $date operator.

Syntax using ISO 8601: { "$date": "<ISO_8601_DATE_TIME>" }

Syntax using Unix timestamp: { "$date": <UNIX_TIMESTAMP_IN_MILISECONDS> }

Example API request creating transaction document with created date field using ISO 8601:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "transaction",
    "attributes": {
      "created": { "$date": "2017-11-07T12:06:57Z" }
    }
  }
}' \
-X POST https://api.jazer.io/resources/transaction

The response will contain created transaction document where field created is internally stored as a date and in the response represented as ISO 8601 date string.

{
  "data": {
    "type": "transaction",
    "id": "5a023f92ac61052bff2f4024",
    "attributes": {
      "created": "2017-11-07T12:06:57.000Z"
    },
    "links": {
      "self": "https://api.jazer.io/resources/transaction/5a023f92ac61052bff2f4024"
    }
  }
}

Note

By default string values containing ISO 8601 date are not automatically converted to date structures. Explicit conversion is needed using $date operator.

Long

Forcing number to be stored as a long can be done using $numberLong operator.

Syntax: { "$numberLong": "<NUMBER>" }

Example API request creating transaction document with a counter field with the value 123:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "transaction",
    "attributes": {
      "counter": { "$numberLong": "123" }
    }
  }
}' \
-X POST https://api.jazer.io/resources/transaction

The response contains created transaction document. Value 123 of a field counter would normally be stored in a 32-bit integer if not for $numberLong operator which forced storage to a 64-bit long.

{
  "data": {
    "type": "transaction",
    "id": "5a024d63ac61052d59b453a7",
    "attributes": {
      "counter": 123
    },
    "links": {
      "self": "https://api.jazer.io/resources/transaction/5a024d63ac61052d59b453a7"
    }
  }
}

Note

By default, numbers are stored in integers (signed 32-bit) if they can fit. Otherwise, they are stored in longs (signed 64-bit).

Decimal

Store a number with decimal precision using $numberDecimal operator.

Syntax: { "$numberDecimal": "<NUMBER>" }

Example API request creating transaction document with a cost field with the value 123456789123456789.987654321:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "transaction",
    "attributes": {
      "cost": { "$numberDecimal": "123456789123456789.987654321" }
    }
  }
}' \
-X POST https://api.jazer.io/resources/transaction

The response contains created transaction document with a cost field stored in decimal precision:

{
  "data": {
    "type": "transaction",
    "id": "5a8a8e16a01c5b0f3996f1ba",
    "attributes": {
      "cost": 123456789123456789.987654321
    },
    "links": {
      "self": "https://api.jazer.io/resources/transaction/5a8a8e16a01c5b0f3996f1ba"
    }
  }
}

Note

By default floating point numbers are all stored in 64-bit doubles. More precision can be requested with $numberDecimal operator which will store floating point numbers inside 128-bit decimals.

ObjectID

Resource document primary ID is not a string, but an object. Comparing it to a string value will not yield correct result. Converting string to a object ID is possible using $oid operator.

Syntax: { "$oid": "<DOCUMENT_ID>" }

Example API request fetching transaction documents using IDs:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X GET https://api.jazer.io/resources/transaction?filter[id]={ "$in": [{ "$oid": "5a023f92ac61052bff2f4024" }, { "$oid": "5a024d63ac61052d59b453a7" }]}

Response contains transaction document with requested IDs:

{
  "data": [{
    "type": "transaction",
    "id": "5a023f92ac61052bff2f4024",
    "attributes": {
      "created": "2017-11-07T12:06:57.000Z"
    },
    "links": {
      "self": "https://api.jazer.io/resources/transaction/5a023f92ac61052bff2f4024"
    }
  }, {
    "type": "transaction",
    "id": "5a024d63ac61052d59b453a7",
    "attributes": {
      "counter": 123
    },
    "links": {
      "self": "https://api.jazer.io/resources/transaction/5a024d63ac61052d59b453a7"
    }
  }],
  "links": {
    "first": "https://api.jazer.io/resources/transaction?page[offset]=0&page[limit]=20",
    "last": "https://api.jazer.io/resources/transaction?page[offset]=0&page[limit]=20",
    "prev": null,
    "next": null
  }
}