Events API

The Events API is a set of RESTful web services to allow programmatic interaction with the Events application. It is being developed based on the standard defined by {json:api}, but not strictly nor fully at this point.

Version Info

The Events API is namespaced by version, to allow evolution while maintaining backwards compatibility. The current version is v5.

• A request to the current version will look like: /RST/events/api/public/v5/...
• An example to a legacy version looks like: /RST/events/api/public/v1/...

Response Information

Response HTTP status codes are still being worked out, and should be considered somewhat volatile. However, to enable client certainty and development, the following assumptions should be true:

• Any 200 status codes can be assumed to have completed successfully
• Any 400 status codes can be assumed to have failed, due to a client/request issue
• Any 500 status codes can be assumed to have failed, due to a server issue

Standard Parameter Information

Recommended format for all date/time parameters is ISO 8601, in UTC time zone (i.e. "2017-11-04T17:43:44,3456Z").

By default, Events API calls default to a limit of 500 results. Clients can apply a different limit with the 'limit' parameter.

An API call that returns a collection may implement the 'span' parameter to restrict results to only those records that fall within the date/time-span defined in the parameter value.

Important notes:

• The value of the 'span' parameter must always have exactly one '~' character. When specifying only a start date/time, the '~' will follow the date/time value (2017-10-20T11:43:44,12345Z~), and when specifying only an end date/time, the '~' will precede the date/time value (~2017-10-20T11:43:44,12345Z). When specifying both a start and end date/time, the '~' will come between the date/times (2017-10-20T11:43:44,12345Z~2017-11-20T11:43:44,12345Z).
• The value on either side of the '~' character can be specified as "now" (case-sensitive) in order to indicate that the current date/time should be utilized. v2
• When the "now" string is used to indicate the current date/time for a span, there can also be extra information included to modify the value specified: v3
  • Directly following "now", a "+" or "-" character can be included, followed by an integer. This indicates that a certain number of time units should be added or subtracted to the current date/time to arrive at the value to use in querying.
  • Directly following the integer, the time unit that should be applied to the integer can be specified. It must be preceded by a '.' character. The default unit, if none is specified, is "days".
  • Examples:
    • now+15 : Current date/time plus 15 days
    • now-90.minutes : Current date/time minus 90 minutes
    • now+1.year : Current date/time plus 1 year
    • now-45.seconds : Current date/time minus 45 seconds
    • now-8.months : Current date/time minus 8 months
• Please refer to the documentation page for the API endpoint to see if it supports the 'span' parameter and, if so, what column the 'span' parameter applies to.

For API calls that return collections, the 'delta' parameter can be used to restrict results to only those records that have been created or updated since the date/time specified in the parameter value.

Sorting can be specified for API calls that return collections by specifying the attribute(s) to sort by, comma (',') separated. Descending sort can be indicated by prefixing the attribute with the minus ('-') character.