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

Ops

Overview

This chapter defines the standardized operations of the Haystack REST API. Each operation is 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:

• haystackVersion: Str version of REST implementation, must be "3.0"
• tz: Str of server's default timezone
• serverName: Str name of the server or project database
• serverTime: current DateTime of server's clock
• serverBootTime: DateTime when server was booted up
• productName: Str name of the server software product
• productUri: Uri of the product's web site
• productVersion: Str version of the server software product
• moduleName: module which implements Haystack server protocol if its a plug-in to the product
• moduleVersion: Str version of moduleName

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:

• name: Str name of the operation in the URI namespace
• summary: Str short description of the operation

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 availble to read and write grids.

Request: empty grid

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

• mime: Str MIME type encoded as "mediaType/subType", these value must not include parameters. Any "text/" media type must be be encoded using UTF-8
• receive: Marker tag if server can read this format in requests (client can POST this format)
• send: Marker tag is server can write this format in responses (client can request response in this format)

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:

• filter: required Str encoding of filter
• limit: optional Number which specifies maximum number of entities to return in response

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

• id: a Ref identifier

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

Nav

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.

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

• watchDis: Str debug string required when creating a new watch
• watchId: Str watch identifier which is required to add entities to existing watch. If omitted, the server must open a new watch.
• lease: optional Number with duration unit for desired lease period (server is free it ignore)

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:

• watchId: required Str identifier of the watch
• lease: required Number with duration unit for server assigned lease period

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:

• watchId: Str watch identifier
• close: Marker tag to close the entire watch The request also .

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:

• watchId: required Str identifier of the watch
• refresh: Marker tag to request full refresh

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:

• id: Ref identifier of writable point

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

• id: Ref identifier of writable point
• level: Number from 1-17 for level to write
• val: value to write or null to auto the level
• who: optional username performing the write, otherwise user dis is used
• duration: Number with duration unit if setting level 8

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

• level: number from 1 - 17 (17 is default)
• levelDis: human description of level
• val: current value at level or null
• who: who last controlled the value at this level

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:

• id: Ref identifier of historized point
• range: Str encoding of a date-time range

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:

• id: Ref of the point we read
• hisStart: DateTime timestamp for exclusive range start in point's timezone
• hisEnd: DateTime timestamp for inclusive range end in point's timezone

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

• "today"
• "yesterday"
• "{date}"
• "{date},{date}"
• "{dateTime},{dateTime}"
• "{dateTime}" // anything after given timestamp

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:

• ts: DateTime timestamp of sample in point's timezone
• val value of each timestamp sample

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 an 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