HotelDataHub - Getting Started — HotelDataHub API Docs

Table of contents¶

Introduction
Authentication token
Login request
Verify and refresh the token
Using Swagger
Using Swagger without logging in

Introduction¶

This article explains how to query and use the HotelDataHub API through the Swagger platform.

There you'll find the different endpoints (URLs) and the information you need to provide for each one in order to use the API correctly.

To access Swagger, visit the following link: https://app.hoteldatahub.io/swagger/

All of this API v1 documentation (the guides in this section) is publicly available, without needing to log in, at: https://app.hoteldatahub.io/api/docs/en/

Once inside, to browse the methods and see the different endpoints, just click on the desired section and all of its information will expand.

Expanding a section shows all of its methods and endpoints. To make a request to the API, always concatenate the base URL with the desired endpoint:

Base URL: https://app.hoteldatahub.io/api/v1/

Example: https://app.hoteldatahub.io/api/v1/contacts/

Besides giving you all the information about the API, the Swagger platform provides mechanisms to make real requests, so you can check how each endpoint behaves.

Authentication token¶

To use the API's requests, you need an authentication token. The token must be added to the header of every request.

{
  "content-type": "application/json",
  "Authorization": "Token token_value"
}

Important: Replace token_value with the token obtained from the login/ endpoint.

To obtain a token, make a POST request to the endpoint:

https://app.hoteldatahub.io/api/v1/login/

Below are the fields to send in the body of that request:

{
  "username": "username_provided_by_HotelDataHub",
  "password": "password_provided_by_HotelDataHub"
}

You can also find this request in Swagger.

Important: Every token expires 24 hours after it is obtained. If an expired token is used to make a request, the API returns a 401 Unauthorized error.

Verify and refresh the token¶

The API uses a sliding token: a single token that both authenticates requests and renews itself. There is no separate refresh token.

There are three ways to keep track of the token's validity and refresh it:

Use the token until you get a 401 error: Use the token obtained at login until a request returns a 401 error. At that point, log in again to get a new token.
Verify before each request: Before each request, make a POST to https://app.hoteldatahub.io/api/v1/token-verify/ with the token in the body to confirm it is still active. If it returns 401, log in again.
```
{ "token": "current_token_value" }
```
Refresh periodically: Before 24 hours have passed, make a POST to https://app.hoteldatahub.io/api/v1/token-refresh/ sending the current token. The API returns the same token with its expiration renewed for another 24 hours.
```
{ "token": "current_token_value" }
```
Response:
```
{ "token": "new_token_value" }
```

Using Swagger¶

To make requests through Swagger (except for the login request), you must log in by clicking the "Django Login" button at the top of the page. A login form will appear, where you enter the same credentials used to obtain the authentication token.

Once logged in, you can make any request by clicking the "Try it out" button and filling in the JSON file or text fields required for the request. The text field information is added as a parameter or as part of the URL.

Fields marked with a red asterisk (*) are required.

Once you've entered the information, click "Execute" and the platform will show you the server's response in the following fields:

Curl: shows the information received by the server.
Request url: shows the endpoint the request was sent to.
Server response:
Code: the server's response code.
Details: description of the response code.
Response body: the JSON response file; this field includes a "Download" button, where you can download the file.
Response headers: information about the response header.

For more information about the values to send or receive at each endpoint, see the following documentation:

Contacts
Movements

Using Swagger without logging in¶

You can also make requests through Swagger using a valid token. As always, you obtain the token via the login request, and to insert it into the Swagger session, click the "Authorize" button, next to the "Django Login" button mentioned in the previous section.

Clicking that button opens a window with the "Bearer" scheme. In the value field, enter the token with the Token prefix:

Token token_value

Once entered, confirm with the green "Authorize" button.

Note: when using Swagger this way, every time you refresh the page you have to enter the token again.