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:**

.. sourcecode:: http

    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.