TOC

  1. Intro
  2. TagModel
  3. Structure
  4. TimeZones
  5. Units
  6. Grids
  7. Filters
  8. Zinc
  9. Json
  10. Trio
  11. Csv
  12. Rest
  13. Ops
    1. Overview
    2. About
    3. Ops
    4. Formats
    5. Read
    6. Nav
    7. WatchSub
    8. WatchUnsub
    9. WatchPoll
    10. PointWrite
    11. HisRead
    12. HisWrite
    13. Invoke Action
  14. Auth
  15. VFDs
  16. Networks
  17. Energy
  18. Zones
  19. AHUs
  20. VAVs
  21. UnitaryEquips
  22. Chillers
  23. Boilers
  24. Tanks
  25. ElecPanels
  26. Lighting
  27. Builds
  28. Bacnet
  29. ChangeLog
  30. License
Rest Auth

Ops

Overview

This chapter defines the standardized operations of the Haystack REST API. Each operation specifies the format and options of the request grid and response grid.

About

The about op queries basic information about the server.

Request: empty grid

Response: single row grid with following columns:

Ops

The ops op queries which operations are available on the server.

Request: empty grid

Response: grid where each row represents a single operation with the following columns:

Example of response in Zinc:

ver:"3.0"
name,summary
"about","Summary information for server"
"ops","Operations supported by this server"
"formats","Grid data formats supported by this server"
"read","Read records by id or filter"

Formats

The formats op is used to query which MIME types are available to read and write grids.

Request: empty grid

Response: grid where each row represents one supported MIME type with following columns:

Example of response in Zinc:

ver:"3.0"
mime,receive,send
"text/csv",,M
"text/plain",M,M
"text/zinc",M,M

Read

The read op is used to read a set of entity records either by their unique identifier or using a filter.

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

Request (by id): a grid of one or more rows and one column:

Response: grid with a row for each entity read. If a filter read and no matches were found this will be an empty grid with no rows. If a read by id, then each row corresponds to the request grid and its respective row ordering. If an id from the request was not found, the response includes a row of all null cells.

Example of filter read request:

ver:"3.0"
filter,limit
"point and siteRef==@siteA",1000

Example of read by id with three identifiers:

ver:"3.0"
id
@vav101.zoneTemp
@vav102.zoneTemp
@vav103.zoneTemp

Example of a read response where an id is not found:

ver:"3.0"
id,dis,curVal
@vav101.zoneTemp, "VAV-101 ZoneTemp",74.2°F
N,N,N
@vav103.zoneTemp, "VAV-103 ZoneTemp",73.8°F

Note: a read operation on points returns the last known values for curVal and curStatus. It does not force cur value refresh from downstream data sources. For those cases you must use the watchSub operation.

The nav op is used navigate a project for learning and discovery. This operation allows servers to expose the database in a human-friendly tree (or graph) that can be explored.

Request: a grid with a single row and a navId column. If the grid is empty or navId is null, then the request is for the navigation root.

Response: a grid of navigation children for the navId specified by the request. There is always a navId column which indicates the opaque identifier used to navigate to the next level of that row. If the navId of a row is null, then the row is a leaf item with no children.

Navigation rows don't necessarily always correspond to records in the database. However, if the navigation row has an id column then it is safe to assume the row maps to a record in the database. Clients should treat the navId as an opaque identifier.

WatchSub

The watchSub operation is used to create new watches or add entities to an existing watch.

If the entities subscribed are themselves proxies for external data sources, then this operation should perform a downstream data refresh. For example if a Haystack gateway is used to proxy BACnet points, then a watch subscription to the Haystack points might initiate a poll or COV subscription to the downstream BACnet points. It is an implementation detail whether the data refresh occurs synchronously or asynchronously. Clients should expect that the latest data might not be available until a subsequent watchPoll operation.

Request: a row for each entity to subscribe to with an id column of Ref values. In addition the following grid metadata is specified:

Response: rows correspond to the current entity state of the requested identifiers using same rules as read op: each response row corresponds to the request grid and its respective row ordering. If an id from the request was not found, the response includes a row of all null cells. Grid metadata is:

If the reponse is an error grid, then the client must assume the watch is no longer valid, and open a new watch.

It is possible that clients may use an id for the subscription which is not the server's canonical id (for example if multiple aliases might be used to reference an entity). The canonical id is the one returned by the server in the watchSub response. Servers must use this same id during watchPoll operations. Clients must not assume that the id used by the watchSub request is the same id used by the watchSub response and watchPoll responses; however, the order of rows in watchSub request/response is guaranteed to allow clients to perform a mapping.

WatchUnsub

The watchUnsub operation is used to close a watch entirely or remove entities from a watch.

Request: a row with the id column and Ref values for each entity to unsubscribe (if the watch is not be closed). Grid metadata:

Response: empty grid

If the reponse is an error grid, then the client must assume the watch is no longer valid, and open a new watch.

WatchPoll

The watchPoll operation is used to poll a watch for changes to the subscribed entity records.

Request: grid metadata:

Reponse: grid where each row correspondes to a watched entity. The id tag of each row identifies the changed entity and correlates to the id returned by watchSub response. Clients must assume no explicit ordering of the rows. If the poll was for changes only, only the changed entities since last poll are returned. If no changes have occurred, then an empty grid is returned. If the poll is a full refresh, then a row is returned for each entity in the watch (invalid identifiers are not be included).

If the reponse is an error grid, then the client must assume the watch is no longer valid, and open a new watch.

PointWrite

The pointWrite op is used to read the current status of a writable point's priority array and optionally write to a given level.

Request (read): a grid with a single row and following columns:

Request (write): a grid with a single row and following columns:

Response: returns a grid with current priority array state with following columns:

HisRead

The hisRead op is used to read a time-series data from historized point.

Request: a grid with a single row and following columns:

Response: rows of the result grid represent timetamp/value pairs with a DateTime ts column and a val column for each scalar value. In addition the grid metadata includes:

The range Str is formatted as one of the following options:

Ranges are exclusive of start timestamp and inclusive of end timestamp. The {date} and {dateTime} options must be correctly Zinc encoded. DateTime based ranges must be in the same timezone of the entity (timezone conversion is explicitly disallowed). Date based ranges are always inferred to be from midnight of starting date to midnight of the day after ending date using the timezone of the his entity being queried.

Example:

// request
ver:"3.0"
id,range
@someTemp,"2012-10-01"

// reponse
ver:"3.0" id:@someTemp hisStart:2012-10-01T00:00:00-04:00 New_York hisEnd:2012-10-02T00:00:00-04:00 New_York
ts,val
2012-10-01T00:15:00-04:00 New_York,72.1°F
2012-10-01T00:30:00-04:00 New_York,74.2°F
2012-10-01T00:45:00-04:00 New_York,75.0°F
..

HisWrite

The hisWrite op is used to post new time-series data to a historized point. The point must already be configured on the server and assigned a unique identifier.

Request: a grid metadata must define id Ref of point to write to. The rows define new timestamp/value samples to write with following columns:

Response: empty grid

Clients should attempt to avoid writing duplicate data. But servers must gracefully handle clients posting out-of-order or duplicate history data. The timestamp and value kind of the posted data must match the entity's configured timezone and kind. Numeric data posted must either be unitless or must match the entity's configured unit. Timezone, value kind or unit conversion is explicitly disallowed.

Example:

Here is an example which posts some new history data to a point:

// request
ver:"3.0" id:@hisId
ts,val
2012-04-21T08:30:00-04:00 New_York,72.2
2012-04-21T08:45:00-04:00 New_York,76.3

Invoke Action

The invokeAction op is used to invoke a user action on a target record. Actions may be used to change setpoints or initiate other types of configuration/control actions. An action is modeled a function which takes zero or more parameters. The arguments for the action's parameters are passed in the request. It is a server local matter to decide what actions are available on a given target and how they are parameterized.

Request: grid metadata must define id Ref of target rec and action Str name. A single row defines the arguments to the action.

Response: undefined

Rest Auth