- OpenActive: RPDE specification - the spec.
- OpenActive: Activation Issue Tracker - help implementing the spec.
- OpenActive: The Steps - what to do after you've implemented the spec.
This specification tackles the generic use-case of unidirectional real-time data synchronisation between two systems, where the receiving system requires only summary data from the origin system.
To get started post an example on the Activation Issue Tracker, build a new API endpoint that conforms to the specifications below, and check it with the validator:
- Paging Specification 1.0 - Section 3-4 explains the concept, Section 4.6 is an example.
- Modelling Specification 1.0
- Validator
Before posting the example implementation to the Activation Issue Tracker, check the following common issues have been included in your thinking:
- Date formats, are you using ISO8601 for all user-facing dates, and integers for timestamps
- Are your user-facing dates ISO8601 format, expressed as local time with a correct offset from UTC (e.g "2016-07-13T20:00:00-05:00"), or as UTC (e.g. "2014-08-12T18:50:00Z")
- Are you using integer "modified" timestamps? (recommended but not required)
- Are records deleted from your system marked with a deleted flag and included in the "Deleted" state
- Does your feed include all historical data from the beginning of time and not just data in the future or from today's date?
- Does the endpoint without any parameters return the first page (from the beginning of time)?
- Have you included as many data fields as possible
- Does your implementation match your internal state as closely as possible (i.e. you are not generating sessions that don't actually yet exist as records in your system from a recurrance rule, but are instead providing the recurrance rule data directly).
- Does each page contain a "license" key (see this issue for details, note that this is not yet updated in the spec)?
- Are Session URLs included in the data block for each session, so a user can find out details from source?
- Is the Next URL present on the last page? The Next URL on the last page (no items) should default to the ID and timestamp of the current request
- Are HTML or Markdown encoded data fields included in plain as well as raw form as separate fields?
- Do embedded related entities have IDs?
- If an embedded related entity is updated, does the main item's timestamp reflect this?
- Are all URLs absolute? Is the next URL absolute?
- Are images included where available, with URLs to each thumbnail size available as well as the original image?
- For image URLs, is an empty string is returned instead of a placeholder image when there is no image available?
- Are all responses returned with header
Content-Type: application/json? - Are the next URL parameters urlencoded?
- Are you using the correct database query to return data for each page, with the
>and=operators correctly placed? See this sample code for a SQL equivalent of the pseudocode in the specification. Thewhereclause should look as follows for the case where afterId and afterTimestamp are both used:WHERE (MODIFIEDDATE = @afterTimestamp AND ID > @afterId) OR (MODIFIEDDATE > @afterTimestamp)
No breaking changes are made within a major version (e.g. 1.x.x), and no additive changes are made within a minor version (e.g. 1.1.x).
| Version | Date Published | Change Log | Change Summary |
|---|---|---|---|
| 0.1.0 | 12 Nov 2015 | Commits Issues | Draft specification circulated for the purposes of gathering feedback. |
| 0.2.0 | 6 Feb 2016 | Commits Issues | Improved to increase clarity, and additional real-time transport options. |
| 0.2.1 | 31 Mar 2016 | Commits Issues | Minor change to case |
| 0.2.2 | 26 Apr 2016 | Commits Issues | Additional implementation guidance added. |
| 0.2.3 | 1 May 2016 | Commits Issues | Migrated from Google Docs to Respec while clarifying minor elements of the specification. |
| 0.2.4 | 26 May 2016 | Commits Issues | Addresses a wide range of feedback from various implementing pioneers reduce ambiguity. |
| 0.3.0 | 21 Jun 2017 | Commits Issues | Recommendation linking to the OpenActive Modelling Opportunity Data Specification. |
| 1.0 | 14 August 2017 | Commits Issues Validator | Increase in clarity and specificity based on many implementations over the past year. |