Skip to content

Commit 136beb9

Browse files
nickevansuknickevansuk
committed
Endpoints
1 parent 1e8e870 commit 136beb9

File tree

2 files changed

+395
-201
lines changed

2 files changed

+395
-201
lines changed

‎EditorsDraft/edit.html

+147-62
Original file line numberDiff line numberDiff line change
@@ -48,17 +48,9 @@
4848
}],
4949

5050
otherLinks: [{
51-
key: "Repo",
52-
value: "We are on Github",
53-
href: "https://github.com/openactive/open-booking-api/",
54-
class: "repo"
55-
}, {
56-
key: "Issues",
57-
value: "Report an issue",
58-
href: "https://github.com/openactive/open-booking-api/issues/"
59-
}, {
6051
key: "Version",
61-
value: "1.0"
52+
value: "1.0",
53+
href: "https://github.com/openactive/open-booking-api/issues/"
6254
}],
6355

6456
logos: [{
@@ -1072,14 +1064,14 @@
10721064
| [`oa:allowSimpleCancellation`](https://openactive.io/allowSimpleCancellation) | - | RECOMMENDED | [`schema:Boolean`](https://schema.org/Boolean) | Whether the event can be cancelled. |
10731065
| [`oa:unitTaxSpecification`](https://openactive.io/unitTaxSpecification) | - | REQUIRED | Array of [`oa:TaxChargeSpecification`](https://openactive.io/TaxChargeSpecification) | Breakdown of tax payable for the OrderItem. |
10741066
| [`schema:acceptedOffer`](http://schema.org/acceptedOffer) | REQUIRED | REQUIRED | [`schema:Offer`](https://schema.org/Offer) | The offer from the associated `orderedItem` that has been selected by the **Customer**. |
1075-
| [`schema:orderedItem`](http://schema.org/orderedItem) | REQUIRED | REQUIRED | [`oa:ScheduledSession`](https://openactive.io/ScheduledSession), [`oa:Slot`](https://openactive.io/Slot), [`oa:HeadlineEvent`](https://openactive.io/HeadlineEvent), [`schema:Event`](https://schema.org/Event) or [`schema:CourseInstance`](https://schema.org/CourseInstance) | The specific bookable Thing that has been selected by the **Customer**. See the [Modelling Specification](https://www.openactive.io/modelling-opportunity-data/) for more information on these types. |
1067+
| [`schema:orderedItem`](http://schema.org/orderedItem) | REQUIRED | REQUIRED | [`oa:ScheduledSession`](https://openactive.io/ScheduledSession), [`oa:Slot`](https://openactive.io/Slot), [`oa:HeadlineEvent`](https://openactive.io/HeadlineEvent), [`schema:Event`](https://schema.org/Event) or [`schema:CourseInstance`](https://schema.org/CourseInstance) | The specific bookable Thing that has been selected by the **Customer**. See the [[!Modelling-Opportunity-Data]] for more information on these types. |
10761068

10771069
Note that [`schema:orderQuantity`](http://schema.org/orderQuantity) is not supported in this version of the specification.
10781070

10791071

10801072
## `Offer`
10811073

1082-
Use of properties of `Offer` defined in the [Modelling Specification](https://www.openactive.io/modelling-opportunity-data/) are also encouraged.
1074+
Use of properties of `Offer` defined in the [[!Modelling-Opportunity-Data]] are also encouraged.
10831075

10841076
| Property | Broker Request | Booking System Response | Type | Notes |
10851077
|--------------------------------------------------------------------|----------|----------|-|------|
@@ -1355,7 +1347,142 @@
13551347
</section>
13561348

13571349

1358-
<section class="normative">
1350+
<section class="normative">
1351+
# Endpoints
1352+
1353+
This API has been defined around the concept of URL discovery. This
1354+
allows resource URLs which match the naming conventions of each **Booking System**.
1355+
1356+
# Paths and Verbs
1357+
1358+
Due to URL discovery, the paths of the endpoints below are illustrative, as the actual paths may vary provided they are consistent within an implementation.
1359+
1360+
| Name | Status | Resource | HTTP Verb | Example Path |
1361+
|------------------------|-------------|------------------|-----------|--------------------------------------------------|
1362+
| Order Creation | REQUIRED | Order collection | POST | `/orders` |
1363+
| Order Feed | REQUIRED | RPDE feed | GET | `/orders-rpde` |
1364+
| OrderItem Cancellation | REQUIRED | OrderItem | PATCH | `/orders/{order-id}/order-items/{order-item-id}` |
1365+
| Order Cancellation | RECOMMENDED | Order | PATCH | `/orders/{order-id}` |
1366+
| Order Status | OPTIONAL | Order | GET | `/orders/{order-id}` |
1367+
1368+
## URL discovery
1369+
1370+
The URL for the initial Order Creation action may be discovered by parsing the
1371+
actions defined in the `potentialAction` property of an object and constructing the appropriate URL from the
1372+
`urlTemplate` property of the `schema:EntryPoint` object contained within the `target`
1373+
property of the `potentialAction` required.
1374+
1375+
An example is below:
1376+
1377+
<pre class="example" title="Example of a potentialAction">
1378+
1379+
"potentialAction": [
1380+
{
1381+
"type": "PayAction",
1382+
"name": "Payment",
1383+
"target": {
1384+
"type": "EntryPoint",
1385+
"urlTemplate": "https://example.com/orders",
1386+
"encodingType": "application/vnd.openactive.v1.0+json",
1387+
"httpMethod": "POST"
1388+
}
1389+
}
1390+
]
1391+
</pre>
1392+
1393+
Since discovery of URLs is an implicit part of the specification, **brokers**
1394+
SHOULD avoid hard-coding URLs for specific actions into their applications and
1395+
client libraries. **Brokers** SHOULD use most applicable URL discovered at the
1396+
point in the workflow they are currently in - e.g. not use a cached URL that has
1397+
been previously successfully used. They should also not attempt to create URLs
1398+
for a specific action based on patterns within previously used URLs.
1399+
1400+
It is the responsibility of **booking platforms** to advertise the URL for
1401+
further activity in the booking workflow at the point of need. For example they
1402+
MUST advertise the URL for `Order` creation when a **broker** requests
1403+
a specific **opportunity** resource and SHOULD advertise it in their RDPE feeds
1404+
since both of these points within the booking workflow are places where a \
1405+
**customer** may wish to check availability.
1406+
1407+
### Dataset site examples
1408+
1409+
<pre class="example" title="Example of Dataset site embedded JSON-LD">
1410+
1411+
&#x3C;script type=&#x22;application/ld+json&#x22;&#x3E;
1412+
{
1413+
"@context": "https://schema.org",
1414+
"keywords": [
1415+
"Sessions",
1416+
"Facilities",
1417+
"Activities",
1418+
"Sports",
1419+
"Physical Activity",
1420+
"OpenActive"
1421+
],
1422+
"license": "https://creativecommons.org/licenses/by/4.0/",
1423+
"distribution": [
1424+
{
1425+
"additionalType": "https://openactive.io/SessionSeries",
1426+
"encodingFormat": "application/vnd.openactive.rpde+json; version=1.0",
1427+
"contentUrl": "https://opendata.leisurecloud.live/api/feeds/fusion-lifestyle-live-session-series",
1428+
"@type": "DataDownload",
1429+
"name": "SessionSeries"
1430+
},
1431+
{
1432+
"additionalType": "https://openactive.io/ScheduledSession",
1433+
"encodingFormat": "application/vnd.openactive.rpde+json; version=1.0",
1434+
"contentUrl": "https://opendata.leisurecloud.live/api/feeds/fusion-lifestyle-live-scheduled-sessions",
1435+
"@type": "DataDownload",
1436+
"name": "ScheduledSession"
1437+
},
1438+
{
1439+
"additionalType": "https://openactive.io/FacilityUse",
1440+
"encodingFormat": "application/vnd.openactive.rpde+json; version=1.0",
1441+
"contentUrl": "https://opendata.leisurecloud.live/api/feeds/fusion-lifestyle-live-facility-uses",
1442+
"@type": "DataDownload",
1443+
"name": "FacilityUse"
1444+
},
1445+
{
1446+
"additionalType": "https://openactive.io/Slot",
1447+
"encodingFormat": "application/vnd.openactive.rpde+json; version=1.0",
1448+
"contentUrl": "https://opendata.leisurecloud.live/api/feeds/fusion-lifestyle-live-slots",
1449+
"@type": "DataDownload",
1450+
"name": "Slot"
1451+
}
1452+
],
1453+
"discussionUrl": "https://github.com/fusion-lifestyle/opendata/issues",
1454+
"documentation": "https://docs.leisurecloud.live/",
1455+
"inLanguage": "en-GB",
1456+
"publisher": {
1457+
"legalName": "Fusion Lifestyle",
1458+
"logo": {
1459+
"@type": "ImageObject",
1460+
"url": "https://res.cloudinary.com/gladstone/image/upload/fusion-lifestyle-live/wfiqlyqy5sjfpo5b6dsl"
1461+
},
1462+
"email": "[email protected]",
1463+
"@type": "Organization",
1464+
"name": "Fusion Lifestyle",
1465+
"description": "Fusion Lifestyle was established in April 2000 following a decision by a London Borough Council to outsource the management of the leisure facilities. Fusion now manages a diverse portfolio of facilities using our specialist expertise to provide sustainable solutions for councils and exciting products and programmes for our customers. Fusion is a national operator managing leisure facilities from Wales to London and as far north as Newcastle. \n\nNo two Fusion sites are the same, we retain the heritage of centres when we refurbish and we are experienced at managing centres from ice rinks to outward bound residential centres, town halls and expansive leisure facilities. We put our energies into providing facilities and programmes that are an attractive proposition to the local community. We respect the history of our centres and it is not uncommon for generations of local residents to hold fond memories of learning to swim in our centres, playing football matches over the years and hosting birthday celebrations at our sites.\n\nFusion is a registered charity, there are therefore no shareholders. We are able to continually reinvest in facilities, products and importantly people.\n",
1466+
"url": "https://www.fusion-lifestyle.com/"
1467+
},
1468+
"datePublished": "2019-02-20T13:22:28.7743707Z",
1469+
"schemaVersion": "https://www.openactive.io/modelling-opportunity-data/2.0/",
1470+
"softwareVersion": "OWS:2.0.1",
1471+
"@type": "Dataset",
1472+
"id": "https://fusionopendata.fusion-lifestyle.com/OpenActive/",
1473+
"name": "Fusion Lifestyle Sessions and Facilities",
1474+
"description": "Near real-time availability and rich descriptions relating to the sessions and facilities available from Fusion Lifestyle, published using the OpenActive Modelling Specification 2.0, and covering a rolling lookhead window of the next 14 days.",
1475+
"url": "https://fusionopendata.fusion-lifestyle.com/OpenActive/"
1476+
}
1477+
&#x3C;/script&#x3E;
1478+
1479+
</pre>
1480+
1481+
1482+
</section>
1483+
1484+
1485+
<section class="normative">
13591486
# Common Requirements
13601487

13611488
This section defines some common functionality that applies to the design of the
@@ -1373,22 +1500,22 @@
13731500
Media types will conform to the following pattern:
13741501

13751502
```
1376-
application/vnd.openactive[.version]+json
1503+
application/vnd.openactive.booking+json; version=[version]
13771504
```
13781505

13791506
The current media type is:
13801507

13811508
```
1382-
application/vnd.openactive.1.0+json
1509+
application/vnd.openactive.booking+json; version=1.0
13831510
```
13841511

13851512
**Brokers** specifying a media type without a version, such as:
13861513

13871514
```
1388-
application/vnd.openactive+json
1515+
application/vnd.openactive.booking+json
13891516
```
13901517

1391-
will recieve data in in the most current format which is 1.0.
1518+
will receive data in in the most current format which is 1.0.
13921519

13931520
If you are building an application as a **broker** and care about the stability
13941521
of the response, or have a client application which is tied to a specific
@@ -1399,6 +1526,8 @@
13991526
that when the Booking API reaches the stability of a 1.0 version that this
14001527
advice may change.
14011528

1529+
<div class="issue" data-number="93"></div>
1530+
14021531

14031532
## Response formats
14041533

@@ -1410,57 +1539,13 @@
14101539

14111540
<pre class="example" title="minimal JSON-LD document">
14121541
{
1413-
"@context": "https://openactive.io/ns/oa.jsonld"
1542+
"@context": "https://openactive.io/"
14141543
}
14151544
</pre>
14161545

14171546
Unless otherwise specified the request and response documents MUST conform to
14181547
the [[!Modelling-Opportunity-Data]] data model.
14191548

1420-
## URL discovery
1421-
1422-
The Booking API has been defined around the concept of URL discovery. This
1423-
allows **booking systems** to create resource URLs which match their own
1424-
terms for naming specific objects such as **events** and **orders**.
1425-
1426-
The URL for a specific action, such as for example providing **payment** details,
1427-
may be discovered by parsing the actions defined in the `potentialAction`
1428-
property of an object and constructing the appropriate URL from the
1429-
`urlTemplate` property of the `schema:EntryPoint` object contained within the `target`
1430-
property of the `potentialAction` required.
1431-
1432-
An example is below:
1433-
1434-
<pre class="example" title="Example of a potentialAction">
1435-
1436-
"potentialAction": [
1437-
{
1438-
"type": "PayAction",
1439-
"name": "Payment",
1440-
"target": {
1441-
"type": "EntryPoint",
1442-
"urlTemplate": "https://example.com/orders",
1443-
"encodingType": "application/vnd.openactive.v1.0+json",
1444-
"httpMethod": "PATCH"
1445-
}
1446-
}
1447-
]
1448-
</pre>
1449-
1450-
Since discovery of URLs is an implicit part of the specification, **brokers**
1451-
SHOULD avoid hard-coding URLs for specific actions into their applications and
1452-
client libraries. **Brokers** SHOULD use most applicable URL discovered at the
1453-
point in the workflow they are currently in - e.g. not use a cached URL that has
1454-
been previously successfully used. They should also not attempt to create URLs
1455-
for a specific action based on patterns within previously used URLs.
1456-
1457-
It is the responsibility of **booking platforms** to advertise the URL for
1458-
further activity in the booking workflow at the point of need. For example they
1459-
MUST advertise the URL for `Order` creation when a **broker** requests
1460-
a specific **opportunity** resource and SHOULD advertise it in their RDPE feeds
1461-
since both of these points within the booking workflow are places where a \
1462-
**customer** may wish to check availability.
1463-
14641549

14651550
## Error handling
14661551

0 commit comments

Comments
 (0)