Component overview

The Experience API works by the client requesting to read, create or update arbitrary components of any Experience product. Multiple components can be served by either of these operations, for example it is possible to retrieve multiple aspects of the same Experience product by issuing the following request:

GET /restapi/v2.0/experience/123/components?componentType=BOOKING_LABELS&componentType=CUTOFF

The above request retrieves BOOKING_LABELS and CUTOFF components of Experience product having id=123.

Note (1): Experience product id (aka the ID component) is always sent back regardless if requested or not.

Note (2): a special component, ALL could be used to retrieve all components. We do discourage from using this component though as this puts excess pressure on resources servicing such requests. ALL component can only be used for data retrieval.

Note(3): if any attribute/value is null, such value is never sent back.

Please refer to Swagger’s ExperienceComponentTypeDto enum for a complete set of components used for retrieval. Each component is also listed in this documentation.

The create and update of each component works slightly differently to retrieval: it is enough to pass relevant JSON section for the said component in order for component processor to ingest the data. For example, update of the above product could be done via

POST /restapi/v2.0/experience/123/components and sending the following body:

The above request will trigger update to booking labels and cutoff components only.

Note (1): last modified date (aka LAST_MODIFIED component) is always updated automatically and sent as a response on any other component update.

Note (2): Sometimes an update of one component might trigger changes in another component. For example, if bookingType is updated from DATE_AND_TIME to PASS, start times of such product would become invisible/unavailable. In such case, relevant components are sent back with the response as well (using same example, START_TIMES component would be sent back on bookingType change).

Note (3): the system will validate and sanitize any HTML data if passed for HTML-allowing fields.

200 (HTTP_OK) response code is returned for successful read, create or update operation.

204 (NO_CONTENT) response code is returned for successful update operation when no changes are made. This can happen if all of incoming changes do not modify the Experience product (has the same values as set prior to modification).

4** family of errors refer to authentication, authorization, body payload, query parameter issues. Body usually contains a more detailed explanation of why this particular request had failed. A special case is 429 error which might occur if the caller exceeds request quota per time unit, currently set to 400 requests per minute per each vendor.

5** family of errors refer to internal Bokun platform issues and/or mishandlings and should be reported to our support.