Last modified: Mon Nov 04 2019 16:15:12 GMT+0000 (Coordinated Universal Time)

How to setup Read API

In this tutorial, you will learn about Winding Tree Read API and how to set it up and work with it.


Step by step

Winding Tree Read API is a REST API that can be used to read hotel inventory registered in Winding Tree ecosystem that conforms to Winding Tree data model. It is a fully stateless and cache-less API that for now does not require any prior user authentication.

Read API currently does not expose or validate any information about the ORG.ID.

Running the API

The recommended way of running Winding Tree ecosystem APIs is via docker images. You can grab the latest stable version of Read API on Docker Hub.

First, you need to download the docker image:

$ docker pull windingtree/wt-read-api

And then you need to run it with a configuration meant for the environment you have chosen. You also need to specify to which Ethereum Node the API will connect. We recommend to register with Infura where you will get an HTTP address such as which you would use as ETH_NETWORK_PROVIDER. Be careful to choose the node with appropriate network (i. e. ropsten or mainnet).

$ docker run -p 8081:3000 -e ETH_NETWORK_PROVIDER=address_to_node -e WT_CONFIG=madrid windingtree/wt-read-api

The Read API is then exposed on port 8081:

$ curl localhost:8081
  "docs": "",
  "info": "",
  "version": "0.14.2",
  "config": "madrid",
  "entrypointAddress": "0xa268937c2573e2AB274BF6d96e88FfE0827F0D4D",
  "directoryAddresses": {
    "hotels": "0x2C29c421D7fd7Be4Cc2bfb6d1a44426E43021914",
    "airlines": "0x7d3Ce0d422D381971Eb2bD9615b58f2df5C9f047"
  "factoryAddresses": {
    "hotels": "0x8E6463ea056d812094Ed514455Ab3C88fc23D59C",
    "airlines": "0x8E6463ea056d812094Ed514455Ab3C88fc23D59C"
  "ethNetwork": "ropsten",
  "dataFormatVersions": {
    "airlines": "0.7.x",
    "hotels": "0.8.x"

If you need more control over your setup, you can configure everything with environment variables passed to docker run command. Detailed documentation can be found in the source code repository.

My data is not showing up!

There are a few possibilities of why this might be happening.

1. The data validation did not pass

The API is trying to check if the off-chain data is in a supported dataFormatVersion (not for the ORG.JSON at the moment). And it is trying to validate the data against the configured specification.

If any of these two checks does not pass, or the data is not available at all, it might render your hotel with a warning or an error. Check for details in the data validation description.

2. The ORG.JSON hash does not match the actual data

If the Read API is configured to check ORG.JSON hashes and your hotel has been setup with a wrong hash stored on chain, it will be marked with as invalid. The API clients won't see the hotel at all.

3. Trust clues did not pass (experimental)

If the Read API is configured to verify trust clues and your hotel does not pass the expected criteria, it will be silently dropped. The API clients won't see the hotel at all. These events can be seen in the API logs and you can check whether trust clues checking is on on the root endpoint of the API.

An important note regarding the validation is, that only the returned fields are validated. So if your hotel is being returned by default, it does not necessarily mean that it is OK as a whole.

The trust clue mechanism will also not pass through any hotel that has an invalid (malformed or expired) guarantee present.

Where to next