Introducción
Este documento es el manual del Identity Manager (IM) API de Kiwilimón y Craftología.
La arquitectura del IM se basa en un REST-API que se encarga de la identificación de los usuarios de los sitios.
Las URL oficiales de la IM-API son:
https://im.kiwilimon.com para Kiwilimón
https://im.craftologia.com para Craftología
Convenciones de escritura
Escribiremos todas las consultas a la API de la manera siguiente:
[GET] /contenedor/:key/data
[GET] es el método de acceso HTTP. Es uno de los cuatro GET, POST, PUT o DELETE (ver capítulo REST).
contenedor es el
contenedor de información que desamos consultar.
:key es la clave del
objeto dentro del contenedor que deseamos consultar y es opcional en caso de ser un contenedor único.
data es el nombre del
recurso que deseamos consultar, y es opcional.
Las respuestas se escriben de la manera siguiente, y siempre son de formato JSON:
REST
El IM se puede acceder a través de una API de tipo
REST.
Cada recurso del IM tiene su propia URL en la API para accederlo.
Según el recurso y las autorizaciones, se puede ver, modificar o borrar estos recursos enviando requerimientos a su URL usando los métodos estándares del protócolo HTTP.
Puede usar los 4 métodos básicos de HTTP:
- GET: para ver un recurso
- POST: para ver/crear/modificar un recurso
- DELETE: para borrar un recurso
- PUT: para modificar un recurso
Respuestas HTTP
Estos son los códigos que la API puede regresar sobre el protócolo HTTP.
Si es un error, el cuerpo de la respuesta contiene la razón del error.
200 (OK): Indica que el manejo de la solicitud GET/POST/PUT/DELETE ha sido exitoso.
400 (Bad request): Indica que la solicitud ha sido mal formada o contiene datos inválidos.
401 (Not authorized): Indica que hay un error en la autenticación de la solicitud (clave API incorrecta, digest equivocado, etc).
403 (Forbidden): Indica que esta clave API no tiene acceso a este recurso.
404 (Not found): Indica que la información solicitada no existe en el GRAPH.
500 (Internal Error): Indica que algo esta mal en el servidor (problemas de instalación/configuración).
501 (Not implemented): Indica que el método/recurso solicitado no esta implementado (no existe).
503 (Unavailable): El sitio se encuentra en mantenimiento (dura normalmente pocos minutos).
Los errores distintos de 200 regresan una descripción del error en el cuerpo
Todas las respuestas 200 con algun error regresan aparte un JSON en el cuerpo con 2 parámetros:
{
error: <numero del error>,
mensaje: '<mensaje correspondiente al error>'
}
Autenticación con la API
Hay dos tipos de servicios en la API :
- Servicios públicos - para acceder a toda la información pública del sitio. Son únicamente métodos GET o POST, para consultar la información.
- Servicios bajo autorización - para acceder a la información individual de cada usuario o servicio. Necesita un token pasado por variable o una cookie que contiene este token.
El token se obtiene con el sistema de autenticación en kiwilimón con los varios servicios del IM
Cabe notar que los tokens son desechables con un timeout que decide el sistema.
Seguridad y accesos
Por defecto, sin token solamente se permiten operaciones GET sobre el IM, y POST en el caso del contenedor de login.
El token de sesión solamente da acceso a la información propia del usuario (servicios privados, por ejemplo agregar a favoritos, borrar la lista del súper, etc)
Para acceder a los servicios avanzados se necesita un token avanzado con derechos otorgados bajo solicitud.
Recursos disponibles
Los recursos disponibles en cada objeto de cada contenedor es variable y depende el contenedor.
Los datos del IM son despachados a través de la API solamente en formato JSON.
-
JSON: datos en formato
JSON (Javascript Object Notation) listo para ser usado por un front-end en Javascript o compatible. Extensión .json
Es importante notar que el formato JSON viene siempre codificado en UTF-8.
