search

openactive / open-booking-api

Repository for the Open Booking API specification
Other
2 stars 3 forks source link

Orders RPDE Feed IDs - Should be UUIDs? #226

Open lukehesluke opened 2 years ago

lukehesluke commented 2 years ago

Summary

In the Open Booking API, in all Orders RPDE feed examples, each RPDE item has the Order's UUID as its id.

e.g.

{
  "next": "https://example.com/api/orders-rpde?afterTimestamp=1521565719&afterId=e11429ea-467f-4270-ab62-e47368996fe8",
  "items": [
    {
      "state": "updated",
      "kind": "Order",
      "id": "e11429ea-467f-4270-ab62-e47368996fe8",
      "modified": 1521565719,
      "data": {
        "@context": "https://openactive.io/",
        "@type": "Order",
        "@id": "https://example.com/api/orders/e11429ea-467f-4270-ab62-e47368996fe8",
        "identifier": "e11429ea-467f-4270-ab62-e47368996fe8",

Afaict, the Open Booking API doesn't mandate that this must be the case, but should it?

This issue proposes that we mandate that, for Orders RPDE feeds, the RPDE ID must be the Order's UUID (i.e. have the same value as the Order's identifier).

This'll make it easier for Brokers to understand what's happened in the feed, and in some cases is necessary to prevent permanent loss of information (see Scenario)

Scenario

Consider this scenario:

  1. An Order is created with UUID ddff9de2-8658-4a2c-9ae7-b9f946705214
  2. The Order is then deleted for some reason (perhaps by the Seller)

The Order will only appear in the feed at step # 2. If this Orders RPDE Feed uses an arbitrary ID as its RPDE ID, then there is no way that the Broker can read that item from the feed and discern which Order was deleted.

The RPDE item may look like:

    {
      "state": "deleted",
      "kind": "Order",
      "id": "1234",
      "modified": 1521565719,
    }

As this has no UUID, the Broker cannot cross-reference it with their own Orders and so have no way of knowing that Order ddff9de2-8658-4a2c-9ae7-b9f946705214 has been deleted.

Additionally...

Additionally, the Test Suite as it is presently written will only work for Orders RPDE feeds which follow this rule

nickevansuk commented 2 years ago

Great point @lukehesluke, and this makes sense to me - and the implementation could get very confusing otherwise, on both sides

nathansalter commented 2 years ago

Yes this makes a lot of sense, although I think we should avoid calling it UUID and use id or identifier instead, as not all implementations will be using UUIDs