Web API
Inicio rápido
Lo primero a saber es que la Web API como tal consta de 2 URLs:
La primera es donde se alojan la gran mayoría de servicios. La otra es la que corresponde a la parte “Administrativa”, donde la mayoría de los servicios no están al alcance de usuarios comunes y sí a un usuario Administrador, justamente. Dentro de los servicios que sí tienen todos acceso se encuentra el que permite hacer el Login (necesario para establecer una sesión y a partir de allí poder consumir los demás servicios a disposición), así como el servicio para saber a qué Bases de Datos se tiene acceso con las credenciales utilizadas al realizar el Login.
Documentación técnica
Toda la documentación técnica que un desarrollador necesita para poder consumir los servicios está publicada en las URLs listadas arriba. Esta documentación es auto-generada cada vez que se despliega una nueva versión de la Web API, por lo que se garantiza que la información allí provista siempre estará al día y consistente. Esto es gracias Swagger, una herramienta que permite documentar y probar las APIs. Es así como no sólo se puede explorar la lista de servicios y sus correspondiente información (cabecera de los mensajes, parámetros, estructura de las respuestas, etc.) sino que también se pueden probar los servicios a través del navegador mismo, sin necesidad de escribir código de programación.
Login
El primer paso a entender es que la Web API (así como casi cualquier otra aplicación de negocios) requiere que el usuario que desee usarla realice un Login, previo al posterior consumo de los servicios. Esto se debe a que al proveer las credenciales (usuario y password) la Web API determina los roles y permisos del usuario y así permitirá o denegará las peticiones a ciertos servicios, en función de si el usuario tiene suficientes permisos.
Por lo tanto, el primer servicio a consumir es el del Login. No obstante, una vez hecho esto satisfactoriamente, la Web API devuelve un Token (in Base64 format), el cual sirve de “vale” para el acceso al resto de los demás servicios,
Autenticación con Token
Este tipo de autenticación es un esquema de autenticación HTTP que cuenta con tokens de seguridad llamados “bearer” (portador), ya que para identificarse/autenticarse frente al sistema hay que ser portador de un token. El token es una cadena de caracteres encriptada, que una vez recibida tras realizar un Login exitoso, el cliente debe enviarla siempre en todas las peticiones que haga a la Web API, en función de poder validar y conceder su permiso para dichas acciones.
Authorization: Bearer {token}.
El esquema de autenticación por Bearer fue creado en conjunto con OAuth 2.0 en el RFC 6750.