Dates and Times

From BrAPI-Wiki
Jump to navigation Jump to search
An example timestamp field in Apiary
An example timestamp field in SwaggerHub

Date and timestamp fields are coded in the ISO 8601 standard, extended format.

In the BrAPI specification, dates and timestamps are defined as JSON strings with specific formats. The date format indicates the field should be a simple date with only year, month, and day. The date-time format indicates the field should be a full timestamp, with hours, minutes, and seconds. Milliseconds are optional. Timezones can either be represented as a "Z" to indicate UTC time, or as an offset from UTC time.

The format information for each field can be found in Apiary and SwaggerHub documentation. In Apiary, for a given endpoint, locate the "Response Fields" table. The type for a timestamp field will appear as "string (date-time)". In SwaggerHub, in the Responses section of a given endpoint, click the "Schema" button to open the response as a collapsible schema. In this view, the name of each field will have a data type next to it. Timestamps will be indicated with the value "string($date-time)".

The table below provides examples for the four different ISO 8601 formats which are acceptable in BrAPI.

Format Example
Date yyyy-MM-dd 2017-06-16
Timestamp yyyy-MM-ddThh:mm:ssz 2017-06-16T14:47:23-06:00
Timestamp UTC yyyy-MM-ddThh:mm:ssZ 2017-06-16T20:47:23Z
Timestamp with milliseconds yyyy-MM-ddThh:mm:ss.sssz 2017-06-16T20:47:23.476+04:00