Documentación

Generalidades

La arquitectura de Kiwilimón se basa en un GRAPH que contiene toda la información relevante del sitio.
En necesario que tenga una clave API otorgada para poder usar el GRAPH a través de la API.
Solamente otorgamos claves a las empresas/personas con relaciones comerciales con Kiwilimón.

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 (es opcional).
data es el nombre del recurso que deseamos consultar.
xml es el formato en el cual queremos los datos. Es uno de los tres xml, json o txt.

Las respuestas se escriben de la manera siguiente:
Este ejemplo esta en 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
• POST: para 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.

Autenticación con la API

Para poder usar la API, necesita su clave y su código secreto.
Los puede consultar en este sitio en el menú 'Conectarse' una vez que le otorgamos la clave.

Para formar una solicitud válida, necesita pasar 2 parámetros en la URL:
api_key: la clave de la API que le otorgamos.
digest: el digest calculado en base a la URL solicitada, los parámetros y el código secreto.

Para calcular el digest, se hace de la manera siguiente:

1. Tomar el código secreto como base. El código secreto es una cadena de 30 carácteres, por ejemplo "AAAAAAAAAABBBBBBBBBBCCCCCCCCCC" (sin las comillas). Puedes ver tus datos de acceso aquí.
2. Concatenar el método y la URL del recurso buscado. Por ejemplo queremos el recurso /familia/coc/hijos.xml por GET
3. Concatenar las variables que se envian aparte. En el caso del GET o DELETE es únicamente la clave de la API. La clave API es una cadena de 30 carácteres, por ejemplo nuestra clave es "ZZZZZZZZZZYYYYYYYYYYXXXXXXXXXX" (sin las comillas). Puedes ver tus datos de acceso aquí.
En el caso de un PUT o POST, concatenar despúes de la clave API el contenido de lo que se envia en el cuerpo del mensaje.
4. Aplicar un SHA-256 sobre la cadena. Debe de obtener una cadena de 40 carácteres.
5. Agregar a la URL la clave API y el digest:

Contenedores disponibles

Este GRAPH soporta los contenedores siguientes:
- familias
- familia
- clasificacion
- receta
- menu
- ingredientegrupo
- ingredientepasillo
- ingrediente
- chef
- conexion
Cada contenedor esta detallado en su capítulo correspondiente.

Seguridad y accesos

Por defecto, las claves de la API solamente permiten operaciones GET sobre el GRAPH, y POST en el caso del contenedor conexion.
En caso de requerir más acceso (PUT, DELETE), necesita contactar el staff técnico de Kiwilimon para otorgar las autorizaciones específicas.

Recursos disponibles

Los recursos disponibles en cada objeto de cada contenedor es variable y depende el contenedor.
Sin embargo, los recursos estándares que encontraremos casi en todos son:
- data: para el recurso básico del objeto. En general contiene toda la información afín al objeto mismo.
- hijos: contiene el recurso básico así como sus hijos directos. Este recurso es presente cuando el objeto tiene alguna estructura jerárquica.
- landpage: contiene todos los datos para construir un landpage sobre el objeto. Este recurso es presente cuando existe una landpage correspondiente en el sitio (clasificaciones, familias, chef, etc)
- resumen: contiene los datos resumidos del objeto. Se usa en general para listas ligeras.

Formatos disponibles

Los datos del GRAPH son despachados a través de la API en 3 formatos:
- json: datos en formato JSON (Javascript Object Notation) listo para ser usado por un front-end en Javascript o compatible.
- XML: datos en formato XML en general compatible con webservices, JAVA y sistemas similares.
- text: formato texto plano para cualquier interpretador que puede leer texto o que no es compatible con los dos formatos anteriores.
Es importante notar que los 3 formatos vienen en UTF-8.