SerialBlogger Blog de desarrollo y tecnología

Esto fue idea de Armando, pero ayudé a implementarlo asi que me siento un poco padre de la criatura, y ademas, es una excelente idea como para que muera en nuestra aplicación y no vea la luz.

No se si alguna vez ustedes intentaron acceder a una API, o si alguna vez crearon una. En el fondo la idea es tener una interface para comunicar distintos sistemas. Cuanto mas simple sea esta interface, mas facil va a ser la comunicacion, ergo mas gente la va a poder usar.

Get Real, nadie lee la documentación

Como toda API, la de Cajabox está siendo documentada (ya tiene nombre y todo, y ojo que el nombre es una pista importante), pero cuanto menos cosas haya que aclarar porque estas son obvias, mejor será, y es por eso que nos tomamos el trabajo de crear este feature o detalle que me gustaria ver en mas lugares.

Cómo trabaja una API

Dije que una API era una comunicacion, por lo tanto lo minimo que vamos a tener es un pedido y una respuesta.

El pedido puede hacerse de muchisimas maneras, a mi la que mas me agrada y mas usable me parece, es hacerlo a travez de la URL, por ejemplo:

http://cajabox.com/api/accion/grande/provolone/false

Lo cual devolvera una respuesta, puede ser desde true o false o algo mas complejo como en el caso de flickr que envia una imagen o set de imagenes.

Incluso en la manera de devolver la respuesta hay muchas variantes, desde CSV, XML o el chico nuevo del barrio, Json (el cual todavia no me acaba de simpatizar).

Pero es en el pedido donde quiero enfocarme, a simple vista no parece dificil. De hecho, es la manera mas simple de todas, llamo a una URL y esta da una respuesta, tal como hacemos todo el tiempo con el navegador.

Pero hay un truco, el orden de los parámetros debe ser siempre ese, sino, puede pasar… lo inesperado. Y sinceramente no me parece muy usable una URL llena de parámetros que, fuera de contexto no tienen sentido.

Cómo hacer para que esto se vuelva mas usable?

Si fuera de contexto no tienen sentido, la respuesta obvia es: darles contexto.

Si se define un nombre para cada parámetro, ganamos dos cosas:

1. Mas usabilidad porque la URL quedaria llena de parametros definidos.
2. Mas flexibilidad porque al tener el nombre del parametro, ya no es indispensable el orden.

La URL quedaria entonces asi:

http://cajabox.com/api/accion/tamanio:grande/sabor:provolone/con_aceitunas:false

Como saben, Cajabox esta construido sobre la base del imponderable CakePHP, asi que este snippet seguramente sea liberado en forma de componente para vuestro disfrute.

Y no, Cajabox no es una aplicacion para pizzerias!