Transport / REST – Bókun developer documentation

RESTful transport option enables the Inventory service to call your server using application/json content type on the arbitrary host, path and port. Inventory Service is completely agnostic to the implementation details, such as programming language and HTTP server used on the plugin side.

In terms of HTTP protocol versions, we are using OkHttp library (version 2) which will make the client to prefer the most efficient transport available, falling back to more ubiquitous protocols. Requests are initiated with HTTP/1.1 only. The following protocols are currently supported:

HTTP/1.1

SPDY/3.1

REST API bindings (stubs)

You can generate the bindings from our Swagger definition which is located in our GitHub repository, https://github.com/Bokun/inventory_api/blob/master/src/main/swagger/inventory_api.json.

Swagger generator can be found here.

If your server implementation is in Java, we recommend using the same bindings which are used by our Sample plugin to avoid any potential discrepancies (refer to the dependencies section of the Gradle build file and look for api-themed artifacts in io.bokun.inventory group). Libraries are hosted on AWS S3 and are made publicly available for download.

NOTE: please refer to field/method comments in gRPC implementation (.proto files) as Swagger only has basic set of documentation available.

REST security

We offer the following security measures to protect the traffic against snooping and unauthorized usage:

Basic access authentication username/password. We can configure our end to use basic access authentication so that every request will carry this authentication data in its payload.

TLS/SSL. We offer the ability for both parties to talk via SSL. It is possible to use self-generated certificates as well, you just need to provide us with the certificate in .crt format. Generally, we will require the certificate if out of the box Java 8 SSL framework does not recognize your Certificate Authority.

Whitelist of IP addresses. We can provide you with a list of IP addresses which are used for our test & production systems. All outgoing requests will be originated by those addresses.

REST timeouts

Inventory Service HTTP client will terminate after a certain amount of time has elapsed, as specified below:

Connect timeout: 10 seconds

Read timeout: 30 seconds

Write timeout: 30 seconds

Please note that lengthy response times have direct impact on the UX.

WARNING: Even if a response from the plugin is accepted by the Inventory Service and falls within the above mentioned time frames, it might be no longer relevant nor considered by the upper chain of consumers. For example, if a booking reservation request originally came from Expedia OTA, their API will timeout within 2400 ms resulting a discrepancy between systems. Please make sure you double check if your plugin is capable of delivering the responses within acceptable time if you plan integration with particular OTA(s). Refer to SLA requirements / timeouts for OTAs for more details.

Caching

We do not offer any caching guidelines as each external system might have different matches between external and Inventory service APIs, stale data patterns or fair usage policies.

The general advice, though, is to cache as much as possible in the plugin (if applicable) in order to minimize the wait on the customer end, resulting in better UX.