HotelDataHub - Primeros pasos

Tabla de contenidos¶

Introducción
Token de autenticación
Petición de Login
Verificar y refrescar el token
Uso del Swagger
Usar Swagger sin iniciar sesión

Introducción¶

En este artículo mostramos como consultar y utilizar la API de HotelDataHub a través de la plataforma Swagger.

En ella, encontramos los diferentes endpoints (URLs) y la información que debemos facilitar en cada uno de ellos para una correcta utilización de la API.

Para acceder al Swagger debemos visitar el siguiente enlace: https://app.hoteldatahub.io/swagger/

Toda esta documentación de la API v1 (las guías de esta sección) está disponible públicamente, sin necesidad de iniciar sesión, en: https://app.hoteldatahub.io/api/docs/

Una vez dentro, para navegar por los métodos y ver los diferentes endpoints, basta con pulsar sobre la sección deseada y toda la información de la misma se desplegará.

Al desplegar una sección se muestran todos sus métodos y endpoints. Para poder realizar una petición a la API, concatenamos siempre la URL base con el endpoint deseado:

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

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

El uso de la plataforma Swagger, además de facilitarnos toda la información sobre la API, nos brinda mecanismos para poder realizar peticiones reales, y así comprobar el funcionamiento de cada endpoint.

Token de autenticación¶

Para poder utilizar las peticiones de la API, necesitamos un Token de autenticación. El Token debe añadirse en el header de cada petición.

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

Importante: Sustituir valor_del_token por el Token obtenido en el endpoint login/.

Para obtener un Token, debemos hacer una petición POST al endpoint:

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

A continuación mostramos los campos que hay que enviar en el body de dicha petición:

{
  "username": "usuario_facilitado_por_HotelDataHub",
  "password": "contraseña_facilitada_por_HotelDataHub"
}

Esta petición también la podemos encontrar en Swagger.

Importante: Cualquier Token caduca a las 24 horas de su obtención. Si se usa un Token caducado para realizar una petición, la API devuelve un error 401 Unauthorized.

Verificar y refrescar el token¶

La API utiliza un token deslizante (sliding token): un único token que sirve tanto para autenticar peticiones como para renovarse a sí mismo. No hay un token de refresco separado.

Existen tres maneras de controlar la validez del token y su refresco:

Usar el token hasta recibir un error 401: Usar el token obtenido en el login hasta que una petición devuelva un error 401. En ese momento se debe repetir el login para obtener un nuevo token.
Verificar antes de cada petición: Antes de cada petición, hacer un POST a https://app.hoteldatahub.io/api/v1/token-verify/ con el token en el body para confirmar que está activo. Si devuelve 401, realizar un nuevo login.
```
{ "token": "valor_del_token_actual" }
```
Refrescar periódicamente: Antes de que pasen 24 horas, hacer un POST a https://app.hoteldatahub.io/api/v1/token-refresh/ enviando el token actual. La API devuelve el mismo token con la caducidad renovada otras 24 horas.
```
{ "token": "valor_del_token_actual" }
```
Respuesta:
```
{ "token": "nuevo_valor_del_token" }
```

Uso del Swagger¶

Para poder realizar peticiones a través de Swagger (exceptuando la petición de login), debemos iniciar sesión pulsando en el botón "Django Login", situado al inicio de la página. Aparecerá un formulario de inicio de sesión, donde introduciremos las mismas credenciales utilizadas para obtener el Token de autenticación.

Una vez que hemos iniciado sesión, podemos realizar cualquier petición haciendo clic en el botón "Try it out" y rellenando la información del archivo JSON o de los campos de texto para las peticiones que lo demanden. La información de los campos de texto se añaden como parámetro o parte de la URL.

Los campos marcados con un asterisco rojo (*) son obligatorios.

Cuando hayamos introducido la información, hacemos clic en "Execute" y la plataforma nos mostrará la respuesta del servidor en los siguientes campos:

Curl: muestra la información que ha recibido el servidor.
Request url: muestra el endpoint donde se envía la petición.
Server response:
Code: código de respuesta del servidor.
Details: descripción del código de respuesta.
Response body: archivo JSON de respuesta, este campo incluye un botón "Download", donde podemos descargar el archivo.
Response headers: información de la cabecera de la respuesta.

Para más información sobre los valores a enviar o recibir en cada endpoint, consultar la siguiente documentación:

Contactos
Movimientos

Usar Swagger sin iniciar sesión¶

Adicionalmente podemos realizar peticiones a través de Swagger utilizando un Token válido. Como siempre, obtenemos el Token a través de la petición login, y para insertarlo en la sesión de Swagger pulsamos en el botón "Authorize", al lado del botón "Django Login" mencionado en el apartado anterior.

Al pulsar dicho botón, se abre una ventana con el esquema "Bearer". En el campo de valor hay que introducir el token con el prefijo Token:

Token valor_del_token

Una vez introducido, confirmamos con el botón verde "Authorize".

Nota: utilizando Swagger de esta forma, cada vez que actualicemos la página, tenemos que introducir de nuevo el Token.