inmensoSofa

A look into various REST APIs

2011-10-31T14:00:00.000+01:00

I have recently been working on a web application for data mining. We were initially using a typical stack of server Java technologies. The web MVC part was written on Struts 2.

Our application is pretty UI intensive and we wanted it to have a nice, modern look and feel. As development went on, we soon found ourselves issuing a good amount of AJAX calls to the server. Without careful planning, this can soon become an unmanageable mixture of HTML, JSON and XML response formats, and dozens or hundreds of different GET and POST requests that expect various parameters.

Our architect soon tackled the issue and we decided to define a full featured REST API for the application (incidentally, we moved to Spring MVC which we found nicer), which we then access from the client side.

REST methods

We have since defined dozens of URLs that handle our application requests. Much has been said about how REST method signatures should look: should resource names be used in singular or plural [1]? is it mandatory to use PUT and DELETE methods and do they need to be idempotent [2]? how do list/search methods look like [3]? Not to forget that there are also some well known implementations that provide default methods for most operations.

Besides, REST is not a protocol, but an application architecture style [4]. Without an strict definition, nowadays there are many REST principles that are sistematically violated in real-world applications: not many REST APIs use hyperlinks as their only method reference (rather, they publish API documentation and expect programmers to directly access their published methods). Not all services use all four HTTP methods (GET, POST, PUT, DELETE) as defined by HTTP. Not all of them have consistent naming rules for resources.

Seeing how loose REST is about API aspect, I have collected a few examples from some of the most famouse services on the Internet, so we can have an oversight of how famous REST APIs look as of today.

Facebook (Graph API)

Facebook publish resources as a graph of social objects [5]. Every object in the social graph has a unique ID. You can access the properties of an object by requesting:

https://graph.facebook.com/ID

For example, the official page for the Facebook Platform has id 19292868552, so you can fetch the object at: https://graph.facebook.com/19292868552.

Responses are JSON:

{
   "name": "Facebook Platform",
   "type": "page",
   "website": "http://developers.facebook.com",
   ...
   "id": 19292868552,
   "category": "Technology"
}

Relationships between objects are called connections and are accessed using the name of the connection:

https://graph.facebook.com/ID/CONNECTION_TYPE
https://graph.facebook.com/me/likes?access_token=...
https://graph.facebook.com/me/friends?access_token=...

And results are also JSON:

{
   "data": [
      {
         "name": "John John",
         "id": "201095685"
      },
      {
         "name": "Andy Andy",
         "id": "202921236"
      },
      ...
   ]
}

You can render the current profile photo for any object by adding the suffix /picture to the object URL. They have consistent support for paging, selecting fields and/or multiple objects in one call, accepting/returning different date formats and fulltext search:

https://graph.facebook.com/bgolub?fields=id,name,picture
https://graph.facebook.com?ids=arjun,vernal
https://graph.facebook.com/search?q=mark&type=user

They also provide support for publishing (via POST) to the appropriate resource, using a few simple parameters. The following URL is used to add a comment to an object:

POST:      https://graph.facebook.com/OBJECT_ID/comments
arguments: message

This API uses only GET and POST. They don't use hyperlinks to reference other objects (for example, lists are composed of object IDs, not URLs).

Twitter

Twitter API [6] is also GET/POST based:

Get user home timeline, users who retweeted a post, followers:

GET statuses/home_timeline
GET statuses/ID/retweeted_by
GET followers/ids

Modifications are done via POST, like the URL used for actually tweeting:

POST statuses/update

These GET and POST methods accept a variety of parameters which are very well documented. Parameters can be used to filter the timespan of the object we want to retrieve, for defining pagination, filtering, whether to include extra metadata about objects returned... Twitter API can also provide a number of response formats: JSON, XML, RSS, Atom.

This is an example of a response list of tweets in JSON format (which is an array of tweet objects):

[
{
    "coordinates": null,
    "favorited": false,
    "created_at": "Fri Jul 16 16:58:46 +0000 2010",
    "truncated": false,
    "entities": {
      "urls": [
        {
          "expanded_url": null,
          "url": "http://www.flickr.com/photos/cindyli/4799054041/",
          "indices": [
            75,
            123
          ]
        }
      ],
      "hashtags": [
      ],
      "user_mentions": [
    ...

Google Custom Search API

This is a very simple API [7]. You can retrieve results for a particular search by sending an HTTP GET request to its URI. The URI for a search has the following format:

https://www.googleapis.com/customsearch/v1?parameters

Parameters have to include the Google API key, the search query and other optional Google query parameters (response format, pagination, search options, filtering...). For example:

GET https://www.googleapis.com/customsearch/v1?key=INSERT-YOUR-KEY&cx=013036536707430787589:_pqjad5hr1a&q=flowers&alt=json

Response formats can be JSON or Atom.

{
"kind": "customsearch#search",
"url": {
"type": "application/json",
"template": "https://www.googleapis.com/customsearch/v1?q\u003d{searchTerms}&num\u003d{count?}&start\u003d{startIndex?}&hr\u003d{language?}&safe\u003d{safe?}&cx\u003d{cx?}&cref\u003d{cref?}&sort\u003d{sort?}&alt\u003djson"
},
"queries": {
"nextPage": [
   {
    "title": "Google Custom Search - flowers",
    "totalResults": 10300000,
    "searchTerms": "flowers",
    "count": 10,
    "startIndex": 11,
    "inputEncoding": "utf8",
    ...

Summary

The big players have very different REST method signature approaches, but all of them share the simplicity and handyness of REST APIs. Being public APIs, all of them are also able to provide results in a number of formats, which allow for an easy consumption of these web services from a huge number of technologies.

As the real world rules for REST web services seem so lax, my advice is to prioritize ease of usage when designing REST services, and leverage the support that your tools or framework provide when building these services. The actual aspect of method signatures and result types is not as important as the naming and type consistency across your various method calls. Using HTTP methods properly is not as critical unless full proxy-cache support is a requirement for your system, and in many cases you'll be safe just using POST for requests that change the state of the system.

I hope this helps showing the different approaches used out there.

[1] http://stackoverflow.com/questions/6845772/rest-uri-convention-singular-or-plural-name-of-resource-while-creating-it
[2] http://stackoverflow.com/questions/7016785/is-put-delete-idempotent-with-rest-automatic
[3] http://stackoverflow.com/questions/1418114/questions-on-proper-rest-design

[4] http://en.wikipedia.org/wiki/Representational_state_transfer

[5] http://developers.facebook.com/docs/reference/api/
[6] https://dev.twitter.com/docs/api
[7] http://code.google.com/apis/customsearch/v1/using_rest.html

Sistemas informáticos con Software Libre

2010-03-28T19:10:00.016+01:00

Hace tiempo que quiero sacar a la luz este artículo, ya que he dedicado buena parte de mi tiempo a los Sistemas Informáticos basados en Software Libre a nivel profesional el último año:

Aibox: nuestra solución informática basadas en Software Libre.

Toda organización necesita hoy en día cierto nivel de servicios TIC como el acceso a Internet, el control de usuarios, los sistemas de ficheros compartidos o las copias de seguridad, por nombrar algunos.

En general, se ha utilizado Windows para proporcionar los servicios TIC en nuestras organizaciones. Y actualmente, Windows Small Business Server es la oferta de Microsoft para las pequeñas y medianas empresas. No soy un fanático de Linux: creo que hoy en día tanto Windows como MacOS son muy buenas herramientas para gestionar servicios corporativos y aportan muy buenas soluciones en diversas áreas, desde las interfaces de usuario hasta el núcleo del sistema. Pero Windows tiene muchos defectos, siendo uno de ellos el no ser Software Libre, con todo lo que ello conlleva. ¿Qué alternativas tenemos?.

Sabemos que GNU-Linux está siendo utilizado en muchísimos escenarios: servidores en Internet, computación distribuída, virtualización... Sabemos que es un pilar fundamental de la estrategia de gigantes como Google y Amazon, y muchos de nuestros bancos. Está incrustado en dispositivos como routers, modems, o reproductores de DVD que utilizamos cada día. Sabemos que está cada vez más presente en los escritorios de los usuarios y que los portátiles, móviles y netbooks se ofrecen con Linux desde hace ya tiempo.

Pero ¿es posible utilizar Linux para la gestión integral de una pila de servicios informáticos en la empresa?. Hace un tiempo que las herramientas necesarias son estables y suficientemente maduras, lo que considero un punto que importante ya que hace cinco años las herramientas necesarias sencillamente no estaban listas para ser usadas ágilmente en un entorno productivo. Ahora la situación es diferente.

Cuando empezamos el diseño de nuestros sistemas para empresas escogimos Ubuntu Server LTS porque proporciona soporte durante 5 años y también proporciona una solución estable de virtualización (Xen, en Ubuntu 8.04). Se estimó que nuestros clientes podrían amortizar fácilmente la instalación a 4 años.

Teníamos claro que queríamos un sistema de configuración fácil y versátil: Zentyal es sencillamente perfecto. Proporciona un sistema fácil de configuración y además trae configuraciones muy robustas para los servicios, proporcionando un sistema productivo muy estable. Zentyal abarca una estupenda (y amplia) selección de servicios que solucionan prácticamente todas las necesidades de una PYME.

Confiamos en Zentyal para la gestión de la red (cortafuegos, redirecciones, dns, dhcp...), el acceso a Internet (Filtrado de acceso web , antivirus y antispam de correo), gestión de usuarios y grupos, redes privadas virtuales y gestión de certificados, servicios de correo, archivos compartidos y controlador de dominio.

Por otra parte, desplegamos una máquina virtual para el la gestión de copias de seguridad y la monitorización, ya que es necesario monitorizar todas las máquinas remotamente que gestionamos para enterarnos de cualquier incidencia. En ocasiones añadimos otros sistemas, como un servidor de clonación de PCs.

Todo el sistema soporta cómodamente a 20 usuarios sobre un Xeon X3460, 2.8Ghz, 8MB Cache con 8 GB DDR3 1333 MHz, y RAID1 1TB SATA2 7200rpm. Con hardware más potente, podemos gestionar unos 45 usuarios exigentes. Y podemos desplegar más máquinas virtuales, como por ejemplo un Windows, si fuese necesario para soportar aplicaciones corporativas.

Podemos supervisar los sistemas de forma remota, podemos centralizar la configuración de las máquinas y disponemos de muchísimas herramientas que no se incluyen por defecto en otros sistemas. También podemos realizar pequeños desarrollos, automatizar tareas o solucionar problemas del software que sería impensable abordar fuera de un entorno de Software de Código Abierto.

Herramientas que nos funcionen tan bien como Dovecot, Bacula, eGroupware, Centreon o VNC no se encuentran tan fácilmente en el universo del software privativo y, si están disponibles, a menudo tienen costes elevadísimos o malas condiciones de soporte, además de suponer un cerrojo tecnológico. Muchas herramientas privativas, a pesar de ser herramientas básicas del sistema, suponen una carga adicional, tanto administrativa como técnica, debido a la gestión de licencias y el acceso a asistencia técnica.

Esto no es tan problemático en un entorno de gran empresa, donde el coste de las licencias y la gestión se difumina en el coste total de la gestión de sistemas. Pero para una pequeña empresa las licencias suponen una partida importante, y en este sentido el software libre permite dedicar la inversión tecnológica a mantener la operatividad y las aplicaciones corporativas.

(Para información a empresas, nuestro enlace comercial es: Aibox: Sistemas Informáticos Gestionados).

Avances en JGF

2009-10-24T19:49:00.004+01:00

Comparto algunos avances de un juego que estoy escribiendo, en forma de capturas de pantalla.

Este jueguecillo de tanques sirve para ejemplificar el uso de mi "framework para juegos (JGF)".

En el jueguecillo, el jugador está atrapado en territorio enemigo y debe escapar atravesando niveles llenos de tanques enemigos. En su camino, otra multitud de tanques intentan acabar con él.

Los tanques y las balas se mueven bastante despacio, pero las balas son muchas y rebotan en las paredes. Por ahora estoy bastante contento con el resultado.

Espero poder distribuir una versión jugable online en unos meses. Por lo demás, sería muy útil la colaboración de un artista 3D y/o de un desarrollador de niveles para mejorar el aspecto gráfico y acelerar el desarrollo. Si alguien se anima puede ponerse en contacto a través de la lista de correo de JGF.

Dinero es Deuda

2009-06-16T14:28:00.001+01:00

Esto no lo enseñan el el colegio...

JGF - Java Game Framework (Early Overview 2009-03-17)

2009-03-30T17:54:00.003+01:00

Presentando un pequeño video que muestra algunas características de JGF, el proyecto libre en que trabajo cuando tengo algo de tiempo libre.

(El sitio del proyecto: http://code.google.com/p/jgf/).

Sexto Sentido

2009-03-13T17:31:00.003+01:00

Cuando era pequeño alucinaba con Sophie, la sobrina del inspector Gadget, porque ésta tenía un LibroOrdenador con el que podía acceder a toda la información y controlar todos los dispositivos a su antojo.

Un teléfono actual supera estas funciones. ¿Cuál es el futuro? Pues librarse del aparato... o hacerlo más accesible. Conseguir que la información que obtenemos llegue directamente al cerebro y responda directamente a nuestros pensamientos. Y aunque eso esté aún algo lejos, las respuestas a esas necesidades: nuevas formas de integración de información y herramientas con nuestra vida diaria y nuestros 5 sentidos, están cada vez más cerca, pasito a pasito:

¡Potencia tu mente!

Entrada sobre el projecto Sexto Sentido en TED
Demostración de Sexto Sentido (video en YouTube, sin la charla)

A veces...

2009-02-24T20:06:00.003+01:00

Hace algún tiempo sugerí a algunos amigos que continuasen la frase "a veces...". Y claro, hubo un montón de "a veces llega un momento en que te haces viejo de repente" (la letra de un tema de Celtas Cortos).

Tal y como prometí, he aquí el resto de los resultados (los nombres se omiten para proteger a los culpables :-)):

a veces... me gustaria cargarme a alguien
a veces no: pero podria ser
a veces... me gustaría volver atrás
a veces nubes pasan
a veces fumo *@#...

(Resumiendo, tengo un amigo al borde de la psicópatía, un indeciso, uno que se arrepiente, uno contemplativo y otro de distendidas costumbres :-D)

JGF -. Java Game Framework

2008-11-30T23:43:00.003+01:00

He estado trabajando recientemente en un framework de desarrollo de juegos en Java. Aquellos interesados podéis visitar la web en Java Game Framework.

But do you know who I am?

2008-08-16T03:15:00.001+01:00

Rápido, pero no lo suficiente...

2008-06-24T00:46:00.001+01:00

Marvin Minsky sobre AI

2008-06-19T01:14:00.001+01:00

Increíble charla de Minsky. Pionero de la Inteligencia Artificial. El artículo de la Wikipedia (http://en.wikipedia.org/wiki/Marvin_Minsky) tampoco tiene desperdicio...

Todo lo que siempre quisiste saber sobre atarte los zapatos

2008-06-18T03:38:00.001+01:00

Después de ver este video me pregunto... ¿soy el único que se ata los zapatos como un capullo? En fin, tampoco es que me ate muchos zapatos la verdad... :D

Entendimiento e Inteligencia Artificial

2008-04-05T00:45:00.002+01:00

¿Cual es la diferencia entre una máquina capaz de convencerte de que te entiende, y una máquina que te entiende?

¿Sería dicha máquina inteligente?

El fin del mundo

2007-12-01T01:19:00.000+01:00

El fin del mundo.

Resulta curioso que, durante mucho tiempo, el fin del mundo fue un lugar, un punto donde el Mundo terminaba y nadie sabía qué había más allá.

Esta visión del fin del mundo resultaba en realidad de lo más oportuna para un ser humano. Nos permitía asumir que el fin del mundo estaba situado en alguna parte. Podíamos pensar en ir y volver del fin del mundo. Podíamos ignorar que no sabíamos nada del fin del mundo y, si esto nos preocupaba por un segundo, podíamos consolarnos inmediatamente con la idea de que el fin del mundo estaba ahí para quien quisiera ir a mirar y averiguarlo). Podíamos dejar el fin del mundo para otros, para quien quisiera conocerlo (ale).

La realidad, sin embargo, no está carente de cierta ironía :-). La tierra resultó ser redonda, y el universo un poquito más grande de lo que nos hubiera gustado. La gente empezó a pensar que, mira por dónde, igual el Mundo iba a tener un final en otra dimensión: la cuarta. Esto mágicamente hace que el Fin del Mundo deje de ser un lugar, para convertirse en un momento. El momento en que el mundo termina y nadie sabe qué hay más allá.

Y esto presenta también desagradables consecuencias: ya no se puede ir y volver del Fin del Mundo debido, principalmente, a que el tiempo parece decidido a ser recorrido en un único sentido. El fin del mundo llegará, y la primera pregunta es ¿estaremos aquí para verlo :-)?.

Sabemos que lo deseas saber todo sobre el fin del mundo. Pero hay algo mucho mejor. Saber lo que pasa DESPUÉS.

El día después del mundo (http://eldiadespuesdelmundo.wordpress.com) es el nuevo Blog del Espigado, artista de quien ya hemos hablado antes y para cuyos textos los eligios de cualquier diccionario son insuficientes. Con una prosa en un registro tan actual que algunos tacharían de transgresora, Espigado utiliza sin embargo a la vez estilos de lo más elegante para desgranar un poquito algún pedacito de sociedad.

Resulta a veces difícil distinguir, sin embargo, donde empieza la sátira y donde termina la cruda realidad, y esto despierta a menudo preguntas en la cabeza del lector, que si se deja llevar pueden terminar en placenteras divagaciones.

¿A qué estáis esperando para haceros fans de El día después del mundo (y para agregarlo a vuestro lector de Feeds: http://eldiadespuesdelmundo.wordpress.com/rss)?.

Sus cinco primeros capítulos ya están ahí fuera, y yo espero impaciente el siguiente.

(í é í á á ?? !!!!)

El Espigado...

2007-03-18T20:35:00.000+01:00

Hace mucho tiempo, en un lugar muy muy pequeño habitado por seres de vida palpitante, una pequeña espora creció hasta convertirse en un ser radiante de pensamiento.

El fantástico Espigado sigue disfrutando de un pensamiento fresco, crítico y equilibrado. Ahora tú también tienes la oportunidad de disfrutar de sus textos, que hablan de la actualidad social con un estilo alegórico a la vez que claro, que nos permite jugar con sus historias, adaptándolas y personalizándolas al lector.

Si te gusta la lectura, no dejes de visitar El Espigado: destila pensamiento y templadas críticas que tanta falta hacen en estos tiempos.

Distribuir aplicaciones en Java

2007-01-22T18:52:00.000+01:00

Aunque sólo será de interés para informáticos, comento que he escrito un artículo para la documentación de jMonkeyEngine (un motor gráfico para Java) sobre cómo distribuir aplicaciones en Java para este motor (aunque es aplicable a la mayoría de las aplicaciones Java).

Está aquí: Packaging and Deploying jME Applications.

La vida es sueño... ¿o no?

2006-12-12T02:35:00.000+01:00

Todo blog tiene una primera entrada que lo estrena. Nosotros hemos invitado a nuestro amigo Pedro Calderón para tener una inauguración por todo lo alto :-).

Con asombro de mirarte,
con admiración de oírte,
ni sé qué pueda decirte,
ni qué pueda preguntarte.
Sólo diré que a esta parte
hoy el cielo me ha guiado
para haberme consolado,
si consuelo puede ser,
del que es desdichado, ver
a otro que es más desdichado.

Cuentan de un sabio, que un día
tan pobre y mísero estaba,
que sólo se sustentaba
de unas yerbas que comía.
¿Habrá otro -entre sí decía-
más pobre y triste que yo?
Y cuando el rostro volvió
halló la respuesta, viendo
que iba otro sabio cogiendo
las hojas que él arrojó.

Quejoso de la fortuna
yo en este mundo vivía,
y cuando entre mí decía:
¿Habrá otra persona alguna
de suerte más importuna?,
piadoso me has respondido;
pues volviendo en mi sentido,
hallo que las penas mías,
para hacerlas tú alegrías,
las hubieras recogido.

Y por si acaso mis penas
pueden aliviarte en parte,
óyelas atento, y toma
las que dellas me sobraren.

Fuente: Biblioteca Virtual Miguel de Cervantes