BookingBug uses HyperMedia Application Language (HAL) so that the API is as flexible and self-describing as possible. The API is currently only configured to return JSON data.
First it’s important that each GET call to the API will return the expected JSON data for the object you are requesting – for example a GET request for service would return expected details about name, description, pricing etc.
The HAL API supplements the result with additional data. This comes in two main parts: _links and _embedded.
In any returned block of data there will be a JSON object called _links. This object contains an array of links that are actions you can perform on the returned object.
This does not refer to the usual actions you would expect from the REST API, the standard CRUD actions are performed as you would expect using HTTP. Instead these might be other actions you could perform next with the data. A good example might be an API call that returned the details of an existing booking. This might have links to:
Each set of links will also always have a _self link. This is always a reference to the object itself.
In the action link that can be executed, there may also be parameters that can be passed in, or optional variables. For example an action on a service might be to discover the days it’s available. The API for this may include variable parameters such as a start date, end date, month or year range. These parameters follow standard templated URI conventions are there are many standard libraries around for parsing them.
Each API response may also come with a set of embedded data. This can be used in a number of different circumstances. For example, if requesting a list of available services for a business, a list of id’s and links will only require each one to be followed to load the data, since in almost all cases you will want the actual data, the API will by default also return the full representation of each item as embedded objects.
Another example is requesting the details of a checked out purchase or booking. This is actually a purchase total, that in turn contains a number of purchase items representing the individual bookings that were made as part of that checkout. When asking for the total, the items are also returned, as well as actions that can be performed on each item.
It’s is strongly recommended that you do make full use of HAL. Not only does it help structure and guide your use of the API, it also allows a degree of forward compatibility – if the API needs to change, and paths or usage changes, by integrating the embedded links and using the URI templates, changes on your side will always be kept to a minimum.
BookingBug reserves the right to change URI paths specified in the API – that will not require coding change if the HAL links are respected.
