ID reference formats

Some resources refer to other resources. And example is the presences resource, which contains references to items and locations. A presence record could look like the following:

{
  "url": "https://<brain-host>/api/presences/5b9a73b82451ee2c9a34123e",
  "id": "5b9a73b82451ee2c9a34123e",
  "item_url": "https://<brain-host>/api/items/5ab4fda4acdba434720bab5f",
  "location_url": "https://<brain-host>/api/locations/5ab4f4dcacdba43475cfc6a4",
  "technology": "rfid",
  "proximity": "immediate",
  "time_created": "2018-09-13T14:27:04.627Z",
  "time_updated": "2018-09-13T14:27:04.627Z"
}

By default, these references are formatted as an URL to facilitate followup requests. Depending on the specific application and query, it may be more convenient to use one of the alternate formats.

Plain ID formatting

To get just the ID of the references, set the id_only query parameter to true. This will change the _url suffix to an _id suffix. For example, with the query GET /api/presences?id_only=true, a presence record could look like the following:

{
  "id": "5b9a73b82451ee2c9a34123e",
  "item_id": "5ab4fda4acdba434720bab5f",
  "location_id": "5ab4f4dcacdba43475cfc6a4",
  "technology": "rfid",
  "proximity": "immediate",
  "time_created": "2018-09-13T14:27:04.627Z",
  "time_updated": "2018-09-13T14:27:04.627Z"
}

Populated formatting

It is also possible to make the Brain resolve and certain references, "populating" them with their record data. This is done by setting the populate query parameter to a comma separated list of properties to populate. For example, with the query GET /api/presences?populate=item,location, a presence record could look like the following:

{
  "url": "https://<brain-host>/api/presences/5b9a73b82451ee2c9a34123e",
  "id": "5b9a73b82451ee2c9a34123e",
  "item": {
    "url": "https://<brain-host>/api/items/5ab4fda4acdba434720bab5f",
    "id": "5ab4fda4acdba434720bab5f",
    "code_hex": "c8e6316e9700000075b5bc42",
    "type": "tag",
    "protocol": "epcgen2",
    "technology": "rfid",
    "label": "Ian's Cup",
    "custom": {},
    "is_present": true,
    "time_last_present": "2018-09-13T14:47:20.952Z",
    "location_url": "https://<brain-host>/api/locations/5a8407cbbcf3b612a95f63f1",
    "move_count": 107,
    "time_moved": "2018-09-13T12:25:02.988Z",
    "sets": [],
    "time_created": "2015-10-19T15:12:11.510Z",
    "time_updated": "2018-09-13T14:47:43.402Z"
  },
  "location": {
    "url": "https://<brain-host>/api/locations/5ab4f4dcacdba43475cfc6a4",
    "id": "5ab4f4dcacdba43475cfc6a4",
    "label": "Kitchen",
    "custom": {},
    "time_created": "2018-02-14T09:56:27.824Z",
    "time_updated": "2018-08-23T07:01:34.691Z"
  },
  "technology": "rfid",
  "proximity": "immediate",
  "time_created": "2018-09-13T14:27:04.627Z",
  "time_updated": "2018-09-13T14:27:04.627Z"
}

Notes about populating references:

• Each populated property will slow down the query to some degree, keep this in mind when using this feature.
• It is not possible to filter or sort on nested properties added with population (e.g. the label of a referenced item).