Documentación - API V6 - Generalidades 🍻

Introducción

Este documento es el manual de la versión 6 de la API de Kiwilimón.
La arquitectura de Kiwilimón se basa en un GRAPH que contiene toda la información relevante del sitio.

Las URL oficiales de la GRAPH-API v6 son https://gr.kiwilimon.com/v6 y https://gr.craftologia.com/v6

A partir de v6, todos los servicios y campos estan estándarizados al inglés, así como el nombre de los campos en las respuestas.
El idioma y el dispositivo solicitados siempre estan copiados dentro del objeto de respuesta (language=, device=).

Convenciones de escritura

Escribiremos todas las consultas a la API de la manera siguiente:
[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 GRAPH se puede acceder a través de una API de tipo REST.
Cada recurso del GRAPH 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 básico
• POST: para solicitar recurso con varios parámetros, o para insertar 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).

Todas las respuestas distintas de 200 regresan aparte un JSON en el cuerpo con 2 parámetros:

Autenticación con la API

Hay dos tipos de servicios en la API V6:
- 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 (servicios del identity manager)
Cabe notar que los tokens son desechables con un timeout que decide el sistema y un token válido es necesario para acceder a estos servicios.

Seguridad y accesos

Por defecto, sin token solamente se permiten operaciones GET y POST de consulta sobre el GRAPH.
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.

Lectura por humano

Cuando se requiere ver el objeto JSON en formato fácil de lectura por un humano (es decir con retornos de linea e identación en cada bloque),
se puede agregar la variable human=1 a la solicitud.

Idiomas

La Graph API es multi-idioma. La solicitud necesita siempre un campo language= puesto.
Es un campo obligatorio en todas las solicitudes.
En caso de GET agregar el idioma dentro del query ?language=es
En caso de POST agregar el idioma como un parámetro extra.
Los idiomas soportados al momento son español (es) e inglés (en).
Poner language=es e language=en para los respectivos idiomas solicitados.

Dispositivos

La Graph API puede enviar datos distintos según el dispositivo que le esta solicitando la data. Es importante siempre pasar el dispositivo solicitante como parámetro.
En caso de GET agregar el dispositivo dentro del query ?device=xxx
En caso de POST agregar el device=xxx como un parámetro extra.
Los dispositivos reconocidos por la API son:
- pc
- mobile
- android (APP)
- ios (APP)
- appletv (APP)
- tizen
- fb (Free Basics)
- alexa

Si el parámetro device es ausente, regresará un error. Es un campo obligatorio.

Imágenes

Cuando las respuestas de la API contienen imágenes, en general estan en los campos "image=" y/o "icon="
Es el nombre de la imagen pura, al cual hay que anteponer el dominio del CDN, ruta, y eventualmente tamaños de thumbs deseados.
Consultar los datos específicos de cada contenedor para obtener la información apropiada de cada imagen.

Si la imagen empieza por http(s):// entonces se puede usar directamente (por ejemplo el avatar del cliente).

Formatos disponibles

Los datos del GRAPH v6 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.