Una de APIs Rest+JSON

759 views
Skip to first unread message

Francho Joven

unread,
Apr 29, 2013, 4:52:59 AM4/29/13
to gente-cac...@googlegroups.com
Hola gente,

Estoy diseñando un API Rest+JSON que va a ser consumida desde Javascript principalmente (posiblemente con AngularJS).

Como es posible que acabe siendo pública quiero diseñarla bien desde todos los puntos de vista (tratamiento de errores, estructuras de datos, convenios de nombres, documentación, etc...)

Mi idea es basarme en los consejos que dio Javier Ramirez en su charla del pasado Codemotion (https://www.youtube.com/watch?v=IssRWUTvXt4) y en cosas que me han gustado de las apis públicas que he consumido (twitter, facebook, paypal, youtube, etc...) 

Como soy un poco novato con esto del Javascrip, me gustaría saber vuestra opinión para afinarla lo máximo posible: cualquier consejo que facilite su uso, apis que os gustan especialmente, etc...

Saludos


Alberto Gimeno Brieba

unread,
Apr 29, 2013, 5:06:38 AM4/29/13
to Gente Cachirulista
Buenas,

Escribí hace poco un artículo sobre cosas que NO me gustan de las nuevas tendencias en las APIs REST

Un par de consejos:

- Siempre devolver un objeto {}. Aunque creas que no vas a devolver nada más que un listado [objeto1, objeto2,…]. Devuelve mejor { result: [objeto1, objeto2,…] } ¿Por qué? Pues porque así podrás añadir cosas en el futuro sin romper compatibilidad hacia atrás.

- Yo siempre devuelvo un "status". Si todo está ok siempre es "Success". Me gusta añadirlo siempre a parte de los status codes de http porque la información es más concreta. Ejemplo: "UserNotFound". Además si permites usar JSONP en ese caso no puedes usar los status codes. Más info de JSONP http://gimenete.tumblr.com/post/48766241623/jsonp-y-las-curiosas-respuestas-json-de-google

Saludos!



2013/4/29 Francho Joven <franc...@gmail.com>

--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 

Francho Joven

unread,
Apr 29, 2013, 1:48:58 PM4/29/13
to gente-cac...@googlegroups.com
Si tu artículo ya lo había leído y estoy de acuerdo con lo que dices.

Lo de devolver siempre un objeto y un estatus me parece una buena idea, lo usaré.

¿Que usáis para documentar en estos casos? ¿una wiki?, ¿un doc?, ¿doc generado con javadoc o similar?...

Saludos
--
FranCHo Joven    
web. http://francho.org    twitter. @francho_lab

Alberto Gimeno Brieba

unread,
Apr 29, 2013, 2:27:37 PM4/29/13
to Gente Cachirulista
Existe algún proyecto como swagger para hacer la documentación sencilla

Pero en general yo suelo hacer un HTML / doc que tenga la información necesaria. Ejemplo:

GET /ruta/que/sea
Parámetros: …. (indicando si son opcionales)
Resultado: …. (indicar un ejemplo o bien decir simplemente "se devuelve un listado de objetos xxx (mirar ejemplo yyy)"
Status codes: Success, InvalidAPIKey, RateLimitExceded, InvalidUserName,…

Los status codes "propios" sirven también para mostrar mensajes internacionalizados. Puedes tener un manejador de errores en la app cliente que tenga su .properties o Localizable.strings o lo que sea con "InvalidUserName" = "Nombre de usuario incorrecto" y el resto de errores posibles. O bien desde el API puedes devolver además de un status un statusDescription ya internacionalizado (pillando en la cabecera HTTP correspondiente el idioma).

Saludos!



2013/4/29 Francho Joven <l...@francho.org>

Dani Latorre

unread,
Apr 29, 2013, 2:47:08 PM4/29/13
to gente-cac...@googlegroups.com
Muy buenos recursos los de Javier Ramirez (nos reímos mucho los que le vimos en el codemotion :D) y el artículo de gimenete. Hace poco les he volví a pegar un repaso, justo hace poco nos ha surgido la necesidad de exponer un API REST/JSONP en el proyecto de un cliente. 

Y la verdad que no sabría decir ningún API que me guste especialmente con la que me haya integrado. Lo que sí me suele resultar engorroso son las que tienen la autentificación con oauth.

En cuanto a documentación, cuando me ha tocado documentar algún pequeño API lo he hecho también a pelo con html para no tener que añadir dependencias a nada. Pero vamos, que también hay mucha gente por ahí con APIs "grandes" que usan algún motor de wikis o algún tipo de gestor de contenidos para facilitarles un poco el trabajo-mantenimiento.
Daniel Latorre
My website: http://www.danilat.com/

Felix

unread,
Apr 30, 2013, 5:07:04 AM4/30/13
to gente-cac...@googlegroups.com
De lo último que he visto en documentación de APIs, me quedaría con la de dropbox, y que coincide con lo que otros han comentado de en html como enumeración y punto. Si te sientes intrépido puedes probar http://apiary.io/ y luego contar la experiencia :P


2013/4/29 Dani Latorre <dani...@gmail.com>



--
Felix

Marcos Murcia

unread,
Apr 30, 2013, 6:53:23 AM4/30/13
to gente-cac...@googlegroups.com
Hola Francho hay un libro de Enrique Amodeo, el que estuvo a punto de dar una charla cachirulense pero las malas fechas veraniegas creo que lo impidió, donde trata el tema de las api rest en un libro desde varios puntos de vista. El libro lo he comprado y merece la pena para ver más enfoques, jamás pensé que darían tanto juego. 

Te dejo en enlace a una primera introducción gratis:


Saludos

Francho Joven

unread,
Apr 30, 2013, 12:43:02 PM4/30/13
to gente-cac...@googlegroups.com
Yo también he usado hasta ahora html "a pelo" para documentar las apis, pero resulta costoso el mantener luego la doc. Por eso había pensado buscar otro enfoque para este. Probaré apiary a ver que tal.

El libro de Enrique está en mi "To read" creo que acaba de subir unos cuantos puestos.

Resumiendo: gracias a todos por vuestros consejos y recomendaciones, me habéis dado mucho tajo ;)

Saludos

Alberto Gimeno Brieba

unread,
Apr 30, 2013, 1:10:25 PM4/30/13
to Gente Cachirulista
Otra idea. En un proyecto en el que trabajé generábamos la documentación con un script que usaba realmente el API y documentaba la respuesta. Te obliga a cambiar el script si cambias el API pero en teoría los cambios en un API (casi) siempre deberían ser compatibles hacia atrás. Así también tienes una manera de saber si has roto algo, y la información de las respuestas siempre están actualizadas.

Eso sí, tanto el script como hacer la documentación a mano son un coñazo igualmente :P


---
Alberto Gimeno Brieba
http://twitter.com/gimenete


2013/4/30 Francho Joven <l...@francho.org>

Alberto Gimeno Brieba

unread,
Apr 30, 2013, 1:12:42 PM4/30/13
to Gente Cachirulista
Otra cosa,

Hay APIs que cuando haces un POST/PUT/PATCH simplemente te dicen que "ok". A mi me gusta que me devuelvan luego lo que obtendría por GET. Así sé sin hacer más peticiones cuál es justamente el estado final del objeto/registro.

Por ejemplo tengo "libros" y hago un PATCH que actualiza el título. Me gustaría que además decirme que todo está ok me devolviera todo lo que devolvería al hacer un GET. Así puedo enseñarle al usuario el estado más fresco de todos los campos del objeto/registro.

My two cents.



2013/4/30 Alberto Gimeno Brieba <gime...@gmail.com>

Francho Joven

unread,
Apr 30, 2013, 1:17:45 PM4/30/13
to gente-cac...@googlegroups.com
Al hilo de lo que dices esta tarde estaba dándole vueltas a documentar con BDD pero he descartado la idea (de documentar así no de hacer tests ;)  porque me parece que el documento resultante no queda todo lo claro que debería.

Saludos

Pablo Jimeno

unread,
Apr 30, 2013, 1:19:11 PM4/30/13
to gente-cac...@googlegroups.com
Yo opino que la charla de @gimenete de API REST es urgente e inexorable :)
Fecha: ?


2013/4/30 Francho Joven <l...@francho.org>



--
Pablo Jimeno Pérez
Mi perfil pablojimeno

Alberto Gimeno Brieba

unread,
May 1, 2013, 12:36:01 PM5/1/13
to Gente Cachirulista
Bueno, pues lo miramos y sí, se podría hacer una charla sobre REST.



2013/4/30 Pablo Jimeno <pdji...@gmail.com>

Pablo Jimeno

unread,
May 1, 2013, 1:54:07 PM5/1/13
to gente-cac...@googlegroups.com
Se me había olvidado, pero para el proyecto que teníamos de tablero Scrum integramos con github y su API está super bien http://developer.github.com/v3/


2013/5/1 Alberto Gimeno Brieba <gime...@gmail.com>

Fernando Pérez

unread,
May 1, 2013, 3:08:51 PM5/1/13
to gente-cac...@googlegroups.com
A proposito de APIs REST, hoy a pasado esto por delante de mi, en twitter:
http://martinfowler.com/articles/richardsonMaturityModel.html

Casualidad o designio divino ?�� No lo se, todav�a tengo que leerlo.

:-)


El 30/04/2013 19:17, Francho Joven escribi�:
Al hilo de lo que dices esta tarde estaba d�ndole vueltas a documentar con BDD pero he descartado la idea (de documentar as� no de hacer tests ;) �porque me parece que el documento resultante no queda todo lo claro que deber�a.

Saludos


El 30 de abril de 2013 19:12, Alberto Gimeno Brieba <gime...@gmail.com> escribi�:
Otra cosa,

Hay APIs que cuando haces un POST/PUT/PATCH simplemente te dicen que "ok". A mi me gusta que me devuelvan luego lo que obtendr�a por GET. As� s� sin hacer m�s peticiones cu�l es justamente el estado final del objeto/registro.

Por ejemplo tengo "libros" y hago un PATCH que actualiza el t�tulo. Me gustar�a que adem�s decirme que todo est� ok me devolviera todo lo que devolver�a al hacer un GET. As� puedo ense�arle al usuario el estado m�s fresco de todos los campos del objeto/registro.

My two cents.
2013/4/30 Alberto Gimeno Brieba <gime...@gmail.com>
Otra idea. En un proyecto en el que trabaj� gener�bamos la documentaci�n con un script que usaba realmente el API y documentaba la respuesta. Te obliga a cambiar el script si cambias el API pero en teor�a los cambios en un API (casi) siempre deber�an ser compatibles hacia atr�s. As� tambi�n tienes una manera de saber si has roto algo, y la informaci�n de las respuestas siempre est�n actualizadas.

Eso s�, tanto el script como hacer la documentaci�n a mano son un co�azo igualmente :P


2013/4/30 Francho Joven <l...@francho.org>
Yo tambi�n he usado hasta ahora html "a pelo" para documentar las apis, pero resulta costoso el mantener luego la doc. Por eso hab�a pensado buscar otro enfoque para este. Probar� apiary a ver que tal.

El libro de Enrique est� en mi "To read" creo que acaba de subir unos cuantos puestos.

Resumiendo: gracias a todos por vuestros consejos y recomendaciones, me hab�is dado mucho tajo ;)

Saludos


El 30 de abril de 2013 12:53, Marcos Murcia <faroale...@gmail.com> escribi�:

Hola Francho hay un libro de Enrique Amodeo, el que estuvo a punto de dar una charla cachirulense pero las malas fechas veraniegas creo que lo impidi�, donde trata el tema de las api rest en un libro desde varios puntos de vista. El libro lo he comprado y merece la pena para ver m�s enfoques, jam�s pens� que dar�an tanto juego.�

Te dejo en enlace a una primera introducci�n gratis:


Saludos


El 30 de abril de 2013 11:07, Felix <sucot...@gmail.com> escribi�:

De lo �ltimo que he visto en documentaci�n de APIs, me quedar�a con la de dropbox, y que coincide con lo que otros han comentado de en html como enumeraci�n y punto. Si te sientes intr�pido puedes probar�http://apiary.io/�y luego contar la experiencia :P


2013/4/29 Dani Latorre <dani...@gmail.com>
Muy buenos recursos los de Javier Ramirez (nos re�mos mucho los que le vimos en el codemotion :D) y el art�culo de gimenete. Hace poco les he volv� a pegar un repaso, justo hace poco nos ha surgido la necesidad de exponer un API REST/JSONP en el proyecto de un cliente.�

Y la verdad que no sabr�a decir ning�n API que me guste especialmente con la que me haya integrado. Lo que s� me suele resultar engorroso son las que tienen la autentificaci�n con oauth.

En cuanto a documentaci�n, cuando me ha tocado documentar alg�n peque�o API lo he hecho tambi�n a pelo con html para no tener que a�adir dependencias a nada. Pero vamos, que tambi�n hay mucha gente por ah� con APIs "grandes" que usan alg�n motor de wikis o alg�n tipo de gestor de contenidos para facilitarles un poco el trabajo-mantenimiento.


El 29 de abril de 2013 20:27, Alberto Gimeno Brieba <gime...@gmail.com> escribi�:

Existe alg�n proyecto como swagger para hacer la documentaci�n sencilla

Pero en general yo suelo hacer un HTML / doc que tenga la informaci�n necesaria. Ejemplo:

GET /ruta/que/sea
Par�metros: �. (indicando si son opcionales)
Resultado: �. (indicar un ejemplo o bien decir simplemente "se devuelve un listado de objetos xxx (mirar ejemplo yyy)"
Status codes: Success, InvalidAPIKey, RateLimitExceded, InvalidUserName,�

Los status codes "propios" sirven tambi�n para mostrar mensajes internacionalizados. Puedes tener un manejador de errores en la app cliente que tenga su .properties o Localizable.strings o lo que sea con "InvalidUserName" = "Nombre de usuario incorrecto" y el resto de errores posibles. O bien desde el API puedes devolver adem�s de un status un statusDescription ya internacionalizado (pillando en la cabecera HTTP correspondiente el idioma).

Saludos!
2013/4/29 Francho Joven <l...@francho.org>
Si tu art�culo ya lo hab�a le�do y estoy de acuerdo con lo que dices.

Lo de devolver siempre un objeto y un estatus me parece una buena idea, lo usar�.

�Que us�is para documentar en estos casos? �una wiki?, �un doc?, �doc generado con javadoc o similar?...

Saludos


El 29 de abril de 2013 11:06, Alberto Gimeno Brieba <gime...@gmail.com> escribi�:

Buenas,

Escrib� hace poco un art�culo sobre cosas que NO me gustan de las nuevas tendencias en las APIs REST
- Siempre devolver un objeto {}. Aunque creas que no vas a devolver nada m�s que un listado [objeto1, objeto2,�]. Devuelve mejor { result: [objeto1, objeto2,�] } �Por qu�? Pues porque as� podr�s a�adir cosas en el futuro sin romper compatibilidad hacia atr�s.

- Yo siempre devuelvo un "status". Si todo est� ok siempre es "Success". Me gusta a�adirlo siempre a parte de los status codes de http porque la informaci�n es m�s concreta. Ejemplo: "UserNotFound". Adem�s si permites usar JSONP en ese caso no puedes usar los status codes. M�s info de JSONP�http://gimenete.tumblr.com/post/48766241623/jsonp-y-las-curiosas-respuestas-json-de-google

Saludos!
2013/4/29 Francho Joven <franc...@gmail.com>
Hola gente,

Estoy dise�ando un API Rest+JSON que va a ser consumida desde Javascript principalmente (posiblemente con AngularJS).

Como es posible que acabe siendo p�blica quiero dise�arla bien desde todos los puntos de vista (tratamiento de errores, estructuras de datos, convenios de nombres, documentaci�n, etc...)

Mi idea es basarme en los consejos que dio Javier Ramirez en su charla del pasado Codemotion (https://www.youtube.com/watch?v=IssRWUTvXt4) y en�cosas que me han gustado de las apis p�blicas que he consumido (twitter, facebook, paypal, youtube, etc...)�

Como soy un poco novato con esto del Javascrip, me gustar�a saber vuestra opini�n para afinarla lo m�ximo posible: cualquier consejo que facilite su uso, apis que os gustan especialmente, etc...

Saludos


--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�

--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�



--
FranCHo�Joven����
web.�http://francho.org�� �twitter.�@francho_lab
--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�

--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�



--
Daniel Latorre
My website: http://www.danilat.com/
--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�



--
Felix
--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�

--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�



--
FranCHo�Joven����
web.�http://francho.org�� �twitter.�@francho_lab
--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�


--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�



--
FranCHo�Joven����
web.�http://francho.org�� �twitter.�@francho_lab
--
Has recibido este mensaje porque est�s suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripci�n a este grupo y dejar de recibir sus correos electr�nicos, env�a un correo electr�nico a gente-cachiruli...@googlegroups.com.
Para obtener m�s opciones, visita https://groups.google.com/groups/opt_out.
�
�

Alberto Gimeno Brieba

unread,
May 14, 2013, 12:10:30 PM5/14/13
to Gente Cachirulista
Buenas,

Acabo de publicar algo de documentación del API de backbeam:

Entre otras cosas puede resultar interesante que tiene un "formato universal" de respuesta que es aplicable a todas o casi todas las respuestas y que resuelve las referencias cíclicas y optimiza los resultados (sin repetir objetos). Por ejemplo si tienes en un blog "comentarios" con "autores" un autor no saldría más de una vez en la respuesta JSON.

También puede resultaros interesante que en el caso de los POST/PUT envía "comandos" o el mecanismo de autorización.

Un saludo!




2013/5/1 Fernando Pérez <fpe...@percea.com>
A proposito de APIs REST, hoy a pasado esto por delante de mi, en twitter:
http://martinfowler.com/articles/richardsonMaturityModel.html

Casualidad o designio divino ?   No lo se, todavía tengo que leerlo.

:-)


El 30/04/2013 19:17, Francho Joven escribió:
Al hilo de lo que dices esta tarde estaba dándole vueltas a documentar con BDD pero he descartado la idea (de documentar así no de hacer tests ;)  porque me parece que el documento resultante no queda todo lo claro que debería.

Saludos


El 30 de abril de 2013 19:12, Alberto Gimeno Brieba <gime...@gmail.com> escribió:
Otra cosa,

Hay APIs que cuando haces un POST/PUT/PATCH simplemente te dicen que "ok". A mi me gusta que me devuelvan luego lo que obtendría por GET. Así sé sin hacer más peticiones cuál es justamente el estado final del objeto/registro.

Por ejemplo tengo "libros" y hago un PATCH que actualiza el título. Me gustaría que además decirme que todo está ok me devolviera todo lo que devolvería al hacer un GET. Así puedo enseñarle al usuario el estado más fresco de todos los campos del objeto/registro.

My two cents.
2013/4/30 Alberto Gimeno Brieba <gime...@gmail.com>
Otra idea. En un proyecto en el que trabajé generábamos la documentación con un script que usaba realmente el API y documentaba la respuesta. Te obliga a cambiar el script si cambias el API pero en teoría los cambios en un API (casi) siempre deberían ser compatibles hacia atrás. Así también tienes una manera de saber si has roto algo, y la información de las respuestas siempre están actualizadas.

Eso sí, tanto el script como hacer la documentación a mano son un coñazo igualmente :P


2013/4/30 Francho Joven <l...@francho.org>
Yo también he usado hasta ahora html "a pelo" para documentar las apis, pero resulta costoso el mantener luego la doc. Por eso había pensado buscar otro enfoque para este. Probaré apiary a ver que tal.

El libro de Enrique está en mi "To read" creo que acaba de subir unos cuantos puestos.

Resumiendo: gracias a todos por vuestros consejos y recomendaciones, me habéis dado mucho tajo ;)

Saludos


El 30 de abril de 2013 12:53, Marcos Murcia <faroale...@gmail.com> escribió:
Hola Francho hay un libro de Enrique Amodeo, el que estuvo a punto de dar una charla cachirulense pero las malas fechas veraniegas creo que lo impidió, donde trata el tema de las api rest en un libro desde varios puntos de vista. El libro lo he comprado y merece la pena para ver más enfoques, jamás pensé que darían tanto juego. 

Te dejo en enlace a una primera introducción gratis:


Saludos


El 30 de abril de 2013 11:07, Felix <sucot...@gmail.com> escribió:

De lo último que he visto en documentación de APIs, me quedaría con la de dropbox, y que coincide con lo que otros han comentado de en html como enumeración y punto. Si te sientes intrépido puedes probar http://apiary.io/ y luego contar la experiencia :P


2013/4/29 Dani Latorre <dani...@gmail.com>
Muy buenos recursos los de Javier Ramirez (nos reímos mucho los que le vimos en el codemotion :D) y el artículo de gimenete. Hace poco les he volví a pegar un repaso, justo hace poco nos ha surgido la necesidad de exponer un API REST/JSONP en el proyecto de un cliente. 

Y la verdad que no sabría decir ningún API que me guste especialmente con la que me haya integrado. Lo que sí me suele resultar engorroso son las que tienen la autentificación con oauth.

En cuanto a documentación, cuando me ha tocado documentar algún pequeño API lo he hecho también a pelo con html para no tener que añadir dependencias a nada. Pero vamos, que también hay mucha gente por ahí con APIs "grandes" que usan algún motor de wikis o algún tipo de gestor de contenidos para facilitarles un poco el trabajo-mantenimiento.
El 29 de abril de 2013 20:27, Alberto Gimeno Brieba <gime...@gmail.com> escribió:
Existe algún proyecto como swagger para hacer la documentación sencilla

Pero en general yo suelo hacer un HTML / doc que tenga la información necesaria. Ejemplo:

GET /ruta/que/sea
Parámetros: …. (indicando si son opcionales)
Resultado: …. (indicar un ejemplo o bien decir simplemente "se devuelve un listado de objetos xxx (mirar ejemplo yyy)"
Status codes: Success, InvalidAPIKey, RateLimitExceded, InvalidUserName,…

Los status codes "propios" sirven también para mostrar mensajes internacionalizados. Puedes tener un manejador de errores en la app cliente que tenga su .properties o Localizable.strings o lo que sea con "InvalidUserName" = "Nombre de usuario incorrecto" y el resto de errores posibles. O bien desde el API puedes devolver además de un status un statusDescription ya internacionalizado (pillando en la cabecera HTTP correspondiente el idioma).

Saludos!
2013/4/29 Francho Joven <l...@francho.org>
Si tu artículo ya lo había leído y estoy de acuerdo con lo que dices.

Lo de devolver siempre un objeto y un estatus me parece una buena idea, lo usaré.

¿Que usáis para documentar en estos casos? ¿una wiki?, ¿un doc?, ¿doc generado con javadoc o similar?...

Saludos


El 29 de abril de 2013 11:06, Alberto Gimeno Brieba <gime...@gmail.com> escribió:

Buenas,

Escribí hace poco un artículo sobre cosas que NO me gustan de las nuevas tendencias en las APIs REST
- Siempre devolver un objeto {}. Aunque creas que no vas a devolver nada más que un listado [objeto1, objeto2,…]. Devuelve mejor { result: [objeto1, objeto2,…] } ¿Por qué? Pues porque así podrás añadir cosas en el futuro sin romper compatibilidad hacia atrás.

- Yo siempre devuelvo un "status". Si todo está ok siempre es "Success". Me gusta añadirlo siempre a parte de los status codes de http porque la información es más concreta. Ejemplo: "UserNotFound". Además si permites usar JSONP en ese caso no puedes usar los status codes. Más info de JSONP http://gimenete.tumblr.com/post/48766241623/jsonp-y-las-curiosas-respuestas-json-de-google

Saludos!
2013/4/29 Francho Joven <franc...@gmail.com>
Hola gente,

Estoy diseñando un API Rest+JSON que va a ser consumida desde Javascript principalmente (posiblemente con AngularJS).

Como es posible que acabe siendo pública quiero diseñarla bien desde todos los puntos de vista (tratamiento de errores, estructuras de datos, convenios de nombres, documentación, etc...)

Mi idea es basarme en los consejos que dio Javier Ramirez en su charla del pasado Codemotion (https://www.youtube.com/watch?v=IssRWUTvXt4) y en cosas que me han gustado de las apis públicas que he consumido (twitter, facebook, paypal, youtube, etc...) 

Como soy un poco novato con esto del Javascrip, me gustaría saber vuestra opinión para afinarla lo máximo posible: cualquier consejo que facilite su uso, apis que os gustan especialmente, etc...

Saludos


--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 

--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 



--
FranCHo Joven    
web. http://francho.org    twitter. @francho_lab
--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 

--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 
--
Daniel Latorre
My website: http://www.danilat.com/
--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 



--
Felix
--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 

--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 



--
FranCHo Joven    
web. http://francho.org    twitter. @francho_lab
--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 


--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 



--
FranCHo Joven    
web. http://francho.org    twitter. @francho_lab
--
Has recibido este mensaje porque estás suscrito al grupo "Gente Cachirulista" de Grupos de Google.
Para anular la suscripción a este grupo y dejar de recibir sus correos electrónicos, envía un correo electrónico a gente-cachiruli...@googlegroups.com.
Para obtener más opciones, visita https://groups.google.com/groups/opt_out.
 
 

--

Francho Joven

unread,
May 15, 2013, 2:57:01 AM5/15/13
to gente-cac...@googlegroups.com
Alberto, tiene muy buena pinta.

Me gusta la idea e poner sufijos para indicar los tipos de datos.

Saludos

Alberto Gimeno Brieba

unread,
Jun 3, 2013, 12:37:22 PM6/3/13
to Gente Cachirulista
Best Practices for Designing a Pragmatic RESTful API




2013/5/15 Francho Joven <l...@francho.org>
Reply all
Reply to author
Forward
0 new messages