mistake-968334_640
En esencia, los servicios REST son bastante sencillos, mucho más que su equivalente en SOAP. Es así porque en este tipo de servicios los conceptos que se usan son pocos y además creo que son universalmente conocidos por los desarrolladores. Y si no lo son, a poco que se les eche un vistazo, no creo que a nadie le cueste mucho entenderlos.
En otras entradas de este blog ya he mencionado cuales son estos conceptos, por ejemplo en Pensando en recursos REST. Sin embargo, veo prácticamente cada día diseños de servicios REST que no son correctos, y esto me enerva … por decirlo finamente 😉 ya que van en contra de las mencionadas normas.
Lo que me más me  contraría es que siguiendo tres reglas básicas, el 90% por ciento de estos errores se evitarían. Serían estas:

1.- hay que usar los códigos HTTP

Por favor, usad los códigos HTTP para lo que son. Quizás los que diseñamos servicios tenemos tendencia a inventarnos códigos de retorno. Así por ejemplo, si nos vienen una petición  errónea a un servicio, pues pensamos (por poner un ejemplo) aquí quedaría molón devolver un código CL5004… que sí que queda bonito: el CL es de Cliente  y el grupo de los 50xx me invento que son por problemas en los parámetros y el 04 es el que ocupa en la secuencia de errores que me he inventado… pues no, esto está mal, muy mal.
Cuando un cliente nos envía una petición con parámetros mal tenemos que devolver un código 400… ¿por qué hay que devolver el 400 y no otro? muy fácil, porque eso es lo que dice el estándar HTTP, ni más ni menos…

400 Bad Request: the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

2.- Hay que usar URIs que identifican los recursos

REST trata de recursos y los recursos son “objetos”, “entidades” o como queramos verlo. Como tales, tienen un nombre… podemos tener el recurso clientetarjetapóliza. Pero nunca tendremos verbos para identificar estos recursos. No tendremos modificarCliente bloquearTarjetabuscar… así de sencillo.
sustantivos sí / verbos no
Además la URI es el identificador del recurso, es decir, no puede haber más de un recurso con la misma URI y las URIs son significativas. Por ejemplo, para ver la tarjeta de un cliente, del cliente nº 345 tendremos /cliente/345/tarjeta y no leerTarjetaCliente?c=345 ni nada parecido.

3.- Usar los métodos HTTP correctos para cada acción

En unos servicios típicos de gestión, tendremos la consulta, el alta, la baja y la modificación. Pues bien, no hace falta inventarse nada porque estos métodos de negocio ya los proporciona el protocolo HTTP: GET, POST, DELETE, PUT y otros pueden hacer perfectamente este trabajo. Así pues, cuando queramos hacer alguna acción de negocio, seleccionemos el método HTTP que  se corresponde y usémoslo.

En definitiva, creo que estaremos de acuerdo que son reglas muy sencillas, que no cuesta mucho seguirlas y que nos evitará hacer servicios web con flagrantes faltas de ortografía