API structure

Starting point

A GET request on the URL /bookprocesses/book returns a HAL+JSON object containing basic details of each book process.

Example response:

HTTP/2 200 OK
Content-Type: application/hal+json

{
    "_embedded": {
        "bookprocess": [
            {
                "id": 1,
                "name": "Climbing tickets",
                "_links": {
                    "self": {
                        "href": "{...}/bookprocesses/book/1",
                        "method": "GET",
                    },
                    "start": {
                        "href": "{...}/bookprocesses/book/1/1",
                        "method": "POST",
                    },
                },
            },
        ],
    },
}

The start link contained in each book process object is the starting URL for a single book process.

Single book process

Each book process step should respond with a HAL+json response containing the following keys:

• form

• recap

• _links

form is a list of elements representing form elements. These elements generally follow the form of HTML5 form elements, e.g. an element with type equal to date represents a date input.

These types of elements may be expected:

• checkbox

• date

• email

• group

• hidden

• number

• select

• static

• tel

• text

• time

recap contains a title string and an items list, containing 0 or more objects with a label and a value.

Links

next:

Book process steps are generally linked together with links with the next-relation, of which the href attribute points to a URI that accepts the input elements in the form list.

recras:bookprocess:validate:

This link can be used to do intermediate validation of the current step. It accepts the input elements of the form list.

recras:bookprocess:make_reservation:

This link relation has the same semantics as the next relation. The difference is that when the request to the recras:bookprocess:make_reservation URI responds with a successful status (HTTP status 20x or 30x) the bookprocess will have completed. Currently the response may be expected to carry a link with the recras:bookprocess:success relation. The response may, however, carry more links.

The reference implementation uses the presence of this relation to present the customer with a different text on the ‘next’-button.

recras:bookprocess:make_reservation_online_payment:

This link relation has the same semantics as the recras:bookprocess:make_reservation relation, except that the response may be expected to carry a payment link. When the request to the recras:bookprocess:make_reservation_online_payment URI responds with a successful status (HTTP status 20x or 30x) the bookprocess will be completed, with the resulting booking in a pending state. The booking will be confirmed after the customer has completed the online payment.

recras:bookprocess:success:

This link relation indicates that the booking is created successfully. The client should be redirected to this URI.

payment:

This link relation follows the semantics described in https://tools.ietf.org/html/rfc8288. The client should be redirected to this URI to complete the payment.