Introducción:
En este artículo mostramos como consultar y utilizar la API de HotelDataHub/Fideltour 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/ .
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 https://app.hoteldatahub.io/api/v1/ con el endpoint deseado.
Ejemplo: https://app.hoteldatahub.io/api/v1/contacts/
El uso de la plataforma Swagger, además de facilitarnos toda la información sobre 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.
- header = {
- "content-type": "application/json",
- "Authorization": "Token valor_del_token"
- }
Importante: sustituir "valor_del_token" por el Token obtenido en el endpoint login/.
Petición de Login:
Como acabamos de mencionar, 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:
- body = {
- "username": "usuario_facilitado_por_HotelDataHub",
- "password": "contraseña_facilitada_por_HotelDataHub"
- }
Esta petición también la podemos encontrar en Swagger(https://app.hoteldatahub.io/swagger/#/login).
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:
Existen tres maneras de controlar la validez del token y su refresco:
- Usar el token obtenido en el login hasta que una petición nos devuelva un error 401, en ese momento se debe repetir el login para actualizar el token y volver a realizar la petición que nos devolvio un 401.
- Antes de cada petición, utilizar el endpoint /token-verify para confirmar que el token esta activo. Si no lo está, realizamos un login para actualizarlo.
- Antes de que pasen 24 horas, utilizar el endpoint /token-refresh para actualizar el token y su caducidad.
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 "Tryout" 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 repuesta, 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 valido. 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 la siguiente ventana, donde podemos insertar el Token y confirmarlo(botón verde "Authorize")
Nota: utilizando Swagger de esta forma, cada vez que actualicemos la página, tenemos que introducir de nuevo el Token.