OpenActive Real-Time Paged Exchange Specification
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
0.1.0
0.2.0
0.2.1
0.2.2
0.2.3
0.2.4
0.3.0
1.0
EditorsDraft
.gitignore
.travis.yml
CONTRIBUTING.md
Gulpfile.js
LICENSE.md
README.md
deploy.sh
deploy_key.enc
package.json

README.md

OpenActive: Real-Time Paged Exchange Specification Build Status

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.

Getting Started

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:

Implementation checklist

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. The where clause should look as follows for the case where afterId and afterTimestamp are both used: WHERE (MODIFIEDDATE = @afterTimestamp AND ID > @afterId) OR (MODIFIEDDATE > @afterTimestamp)

Specification Revision History

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.