Read

Read a set of entity records either by id or by a filter.

Details

URL: /api/read

Method: POST

Request Data Params (by filter): A grid with a single row and following columns:

Column Value description
filter Str encoding of a Project Haystack filter
limit Number which specifies maximum number of entities to return in response

Request Data Params (by id): A grid with one or more rows with the following columns:

Column Value description
id A human friendly display name for the entity

Response (by filter): A grid with a row for each entity read. If no matches were found this will be an empty grid with no rows.

Response: (by id) A grid with a row for each entity read. Each row corresponds to the request grid and its respective row ordering.


Examples

Read by filter

Request

POST /api/read HTTP/1.1
Host: example.com
Authorization: Bearer <authToken>
Accept: application/json
Content-Type: application/json

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "filter"
    }
  ],
  "rows": [
    {
      "filter": "s:site"
    }
  ]
}

Response

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "id"
    },
    {
      "name": "name"
    },
    {
      "name": "dis"
    },
    {
      "name": "site"
    },
    {
      "name": "tz"
    }
  ],
  "rows": [
    {
      "id": "r:192c29f7-c314-4cf6-a1e6-6361f6f666eb site",
      "name": "s:site",
      "dis": "s:Site description",
      "site": "m:",
      "tz": "s:Brisbane"
    }
  ]
}

Read by id, real-time point

Request

POST /api/read HTTP/1.1
Host: example.com
Authorization: Bearer <authToken>
Accept: application/json
Content-Type: application/json

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "id"
    }
  ],
  "rows": [
    {
      "id": "r:1ccbe79f-6c81-449b-b263-df59b04e9889"
    }
  ]
}

Response

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "id"
    },
    {
      "name": "name"
    },
    {
      "name": "cur"
    },
    {
      "name": "curErr"
    },
    {
      "name": "curStatus"
    },
    {
      "name": "curVal"
    },
    {
      "name": "dis"
    },
    {
      "name": "equipRef"
    },
    {
      "name": "kind"
    },
    {
      "name": "point"
    },
    {
      "name": "sensor"
    },
    {
      "name": "siteRef"
    },
    {
      "name": "tz"
    }
  ],
  "rows": [
    {
      "id": "r:1ccbe79f-6c81-449b-b263-df59b04e9889 real-time_point",
      "name": "s:real-time_point",
      "dis": "s:Sample real-time point",
      "cur": "m:",
      "curStatus": "s:ok",
      "curVal": "n:500",
      "equipRef": "r:e09d66a2-0d5b-47a7-b4d8-617447146e2f equip",
      "kind": "s:Number",
      "point": "m:",
      "sensor": "m:",
      "siteRef": "r:192c29f7-c314-4cf6-a1e6-6361f6f666eb site",
      "tz": "s:Brisbane"
    }
  ]
}

Read by fully-qualified name, real-time point

Request

POST /api/read HTTP/1.1
Host: example.com
Authorization: Bearer <authToken>
Accept: application/json
Content-Type: application/json

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "id"
    }
  ],
  "rows": [
    {
      "id": "r:site.equip.real-time_point"
    }
  ]
}

Response

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "id"
    },
    {
      "name": "name"
    },
    {
      "name": "cur"
    },
    {
      "name": "curErr"
    },
    {
      "name": "curStatus"
    },
    {
      "name": "curVal"
    },
    {
      "name": "dis"
    },
    {
      "name": "equipRef"
    },
    {
      "name": "kind"
    },
    {
      "name": "point"
    },
    {
      "name": "sensor"
    },
    {
      "name": "siteRef"
    },
    {
      "name": "tz"
    }
  ],
  "rows": [
    {
      "id": "r:1ccbe79f-6c81-449b-b263-df59b04e9889 real-time_point",
      "name": "s:real-time_point",
      "dis": "s:Sample real-time point",
      "cur": "m:",
      "curStatus": "s:ok",
      "curVal": "n:500",
      "equipRef": "r:e09d66a2-0d5b-47a7-b4d8-617447146e2f equip",
      "kind": "s:Number",
      "point": "m:",
      "sensor": "m:",
      "siteRef": "r:192c29f7-c314-4cf6-a1e6-6361f6f666eb site",
      "tz": "s:Brisbane"
    }
  ]
}

Tagvalue look up by regular expression

Request

POST /api/read HTTP/1.1
Host: example.com
Authorization: Bearer <authToken>
Accept: application/json
Content-Type: application/json

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "filter"
    }
  ],
  "rows": [
    {
      "filter": "s:area =~ /456178.*/"
    }
  ]
}

Response

{
  "meta": {
    "ver": "2.0"
  },
  "cols": [
    {
      "name": "id"
    },
    {
      "name": "area"
    },
    {
      "name": "dis"
    },
    {
      "name": "space"
    }
  ],
  "rows": [
    {
      "id": "r:92b285bf-5197-44f9-9560-9cc0f7e3f203 A big space",
      "area": "n:456178901",
      "dis": "s:A big space",
      "space": "m:"
    }
  ]
}