OpenActive Architecture Documentation

[nickevansuk]

Background

Data users who are new to the ecosystem face an initial hurdle of understanding what OpenActive actually is. On first inspection it might appear from the high level marketing that OpenActive is a single service containing a database of opportunities, and a developer might expect to find a REST API or similar that they can use to query this service.

It has long been recognised that it is important that the OpenActive documentation includes a clear explanation of the architecture of the ecosystem, however this work has simply not been prioritised.

Based on recent confusion expressed by those who are new the OpenActive ecosystem, it seems increasingly urgent that a web page that explains the OpenActive architecture is made available - especially for the benefit of new data consumers.

Proposal

Building on the unfinished attempt in this branch, this issue contains a starter for 10 at this documentation

Comments and questions very welcome, either on this issue or the associated Google Doc - it aims to be both informative and inviting from a data user perspective.

Proposed content included below and in this Google Doc.

---

Using OpenActive data

FAQ

What if I find a problem with a feed? Or if the feed doesn't pass the validator?

The best thing to do is to raise an issue on the publisher's GitHub issues board.

If you can see that the same issue has been reported by another data user on the GitHub issues board, jump on the existing GitHub issue and add a "+1" (perhaps including the size of your audience or detail about your product to add an additional incentive for them to do so).

The GitHub issues board can be accessed as follows

New Dataset Sites

Click the "Discussion" link

Old Dataset Sites

Click the "Documentation" link, then click "Issues" at the top of the page

->

Do I need to store all the data from a feed?

You can store as much or as little data as you want. RPDE has a feature called in-stream filtering that allows the data to be filtered before it is stored. So if you are only interested in data in a specific region, this approach allows you to store a subset of the data only. This is great for prototyping.

Essentially all this means is RPDE is designed for you to filter your data before it is stored, so you can simply programmatically inspect the properties within each item of data, and implement any filter logic that you like.

To simplify geographic and activity-based in-stream filtering and increase data use, feeds are highly recommended to include geo.latitude and geo.longitude properties, and required to include a reference to the OpenActive Activity List.

If you find that these properties are missing, please raise an issue on their GitHub issues board, including these links to the documentation as a reminder.

I'm harvesting a feed that seems to be taking a long time

Newer feeds can be harvested very quickly. Harvesting older feeds can take a long time for two reasons:

1. They include all data from the beginning of time - because they have not yet implemented a retention period.
2. Their RPDE page response times are high - because they have not yet configured a CDN

If you come across an old feed that you want to make use of and are experiencing either of these issues, please do jump on their GitHub issues board (see above) and ask them to implement either implement a retention period or configure a CDN, including these links to the documentation for them as a reminder.