Introduction

Protocol

The API uses the standard of RESTful environments proposed by RFC 6690.  

Requests

The messages are sent with JSON format and Content-Type header set to application/json

Responses

The API responses contains a Content-Type header set to application/json, and a JSON object as body. If the operation results as success, response code will be 200, otherwise there are some error codes we can send back:

Authentication

The implemented authentication of the public API is the 'Basic' HTTP Authentication.

The petition goes in the HTTP headers as is explained here, and is specified in RFC 7617.

API Clarifications

The current version is v1.

Endpoints

All the API endpoints are based on this inital URL:  http://{environment}.ulysescloud.com/api/{version}

All the URL’s in the API are organized in a way which describes the method or action is required. When an endpoint is finished with the name of an entity -let’s say the entity Chain: http://public.ulysescloud.com/api/v1/chain- it means that a list of objects of that entity is going to be returned.

If it finishes with the ID of the entity described in the name -http://public.ulysescloud.com/api/v1/chain/1- it means that the specified entity will be returned with all its fields; even some that do not appear on the list.

All the entity names are singular.

After the version, the methods are organized by our hierarchy. In the top of everything there are chain entities, and in the chain there are property entities:

Chain Entities

Since a chain is the highest element on the hierarchy and the system allows many chains on it, is it completely necessary to specify on which chain we are working on.

http://public.ulysescloud.com/api/v1/chain/{chainId}

There are many Chain entities that could be called from here:

http://public.ulysescloud.com/api/v1/chain/{chainId}/{entity}

Property Entities

As it is explained above, our system has many chains and every chain can have many properties. The URL again is going to be very specific about that, and it must say which chain and property we are asking for.

http://public.ulysescloud.com/api/v1/chain/{chainId}/property/{propertyId}

This new step in the hierarchy is natural and to ask for a property entity should be done like this:

http://public.ulysescloud.com/api/v1/chain/{chainId}/property/{propertyId}/{entity}

Supported Formats

Dates

• Date: yyyy-MM-dd (2017-05-28)
• DateTime: yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (2018-04-12T18:13:32.680Z)
• DateTimeZone: CET

Countries

• Name: Official ISO name
• Code: ISO Alfa 3

Currencies

• Code: ISO 4217

Languages

• Code: ISO 6391

Terminology

Environment: Defines the features that the platform will provide. We have different environment profiles: testing, staging and production.

Version: Changes when the API is updated and defines the milestone of the development where the environment is.

Chain: The hotel chain is a group of properties.

Property: A single hotel, hostel, apartment, etc...

Contents of the documentation