Principios de un webservice RESTful

Hace unos días os explicamos que era un API RESTful, intentando así poner un poco de claridad en estos nuevos términos. Siguiendo esta serie de post, hoy vamos a ver como se está implementando en la web estos conceptos.

Lo primero que hay que recordar es que RESTful pretende, simplemente, crear una serie de principios o patrones sobre los que crear un API de comunicación y, aunque se hizo pensando principalmente para usarse en la WEB, puede ser transportado a otros formatos sin problemas.

Se creó basado en el protocolo HTTP y en su vocabulario, así es muy fácil traspasar los principios de las APIs RESTful a un webservice:

  • Deben estar basadas en URIs, en el anterior post os comentábamos que debería otorgar una interfaz uniforme y única, por lo que es lógico que para definir esta interfaz se trabaje con URIs.
  • Debe enviar la información usando los tipos de formato válidos en Internet. La tendencia suele ser usar formatos JSON para el envío y recepción de datos, aunque otros formatos como XML, Atom, microformatos, o también imágenes, vídeos, PDFs son soportados siempre que sean formatos soportados.
  • Debe seguir los métodos HTTP estándar, los principales son GET, POST, pero también se suelen usar otros como PUT, PATCH o DELETE. Aunque no es necesario, se sigue un patrón para el uso de cada uno de ellos, más adelante vemos esto en detalle.
  • Se deben utilizar los hiperenlaces para referenciar el estado de un elemento y también para poder acceder a estados relacionados. Recordemos que en un sistema RESTful todos los elementos deben poderse acceder desde cualquier otro elemento relacionado, en los webservices, esto se realiza mediante el uso de hiperenlaces.

 

Tipos de recurso

En un API RESTful pueden haber tantos recursos como necesitemos, pero todos se pueden encuadrar en dos tipos de recursos:

  • El recurso colección de elementos, el cual es un conjunto de elementos a los que se puede consultar, añadir, remplazar o simplemente filtrar.
    Por ejemplo, una URI para listar todos los coches disponibles (también se podría filtrar o añadir nuevos coches) podría ser:
    http://unportaldecoches.domain/rest/coches/
  • El recurso elemento, que es una unidad determinada del elemento en cuestión, a esta se le puede añadir valores, borrar o modificar entre otros.
    Por ejemplo, para mostrar el coche con identificador “coche1”
    http://unportaldecoches.domain/rest/coches/coche1/

 

Uso más habitual de los métodos HTTP

Aunque no hay una definición oficial al respecto, si se ha estandarizado el uso de los métodos HTTP como GET, PUT, PATCH, POST y DELETE para realizar determinadas acciones del API.

  • El método GET se asocia con la opción de listar la información.
    • En una colección, listaría los elementos de dicha colección. Y si fuera necesario filtraría por algún parámetro que se pasaría como parámetro.
      http://unportaldecoches.domain/rest/coches/?estado=nuevo
    • En un elemento mostraría la información detallada del elemento o parte de ella según el filtro.
      http://unportaldecoches.domain/rest/coches/coche1/?mostrar=estado
  • El método PUT se asocia con la opción de modificar todo el recurso por uno nuevo.
    • No es habitual usarlo en colecciones de elementos, pero de hacerse, remplazaría toda la colección por la nueva que se envíe.
    • En un elemento, remplazaría todo el elemento por el nuevo elemento enviado.
  • El uso del método PATCH es bastante más reciente y viene a raíz de la necesidad de crear una variante de PUT que no requiera reemplazar todo el elemento, sino solo una parte.
    • En las colecciones es difícil encontrar estas llamadas, pero podrían usarse para modificar sólo una parte de los elementos de la colección.
    • El potencial del método PATCH viene de su uso en los elementos, pudiendo modificar sólo los datos que se envían, evitando así, para cambios menores, el sobrecoste de envío de datos no relevantes.
  • El método POST se asocia a la creación de nuevos recursos.
    • Su uso principal es precisamente en las colecciones, donde se asocia a la creación de un nuevo elemento de dicha colección.
    • Sin embargo, en los elementos rara vez se da el uso, ya que un elemento ya existente no puede crearse a sí mismo.
  • Y por último, el método DELETE, el cual, como no podía ser de otra forma, se asocia con el borrado de recursos.
    • Si se utiliza con una colección intentará borrar por completo la colección.
    • Si, por el contrario, se usa con un solo elemento, borrará este elemento siempre que tenga los permisos oportunos.

Los métodos PUT, PATCH y DELETE deben cumplir que sean idempotentes; deben dar el mismo resultado independientemente de las veces que se realice la misma llamada.

Sin embargo, el método GET se suele llamar como un método seguro o nullipotent ya que las llamadas a este método no debería tener ningún efecto en el lado del servidor.

 

Headers y seguridad

Además de lo anterior, al ser los RESTful unos webservices cliente-servidor sin estado se suele tender a usar los headers de las peticiones para añadir cierta información adicional y transversal a todo el portal.

Algunos ejemplos que se suelen usar dentro de los headers serían:

  • content-type: Indica el formato en el que se está enviando la información.
  • www-authenticate: Indica el tipo de autenticación que se ha usado en el webservice
  • x-api-key: En los casos en los que a un API se puede acceder desde diferentes dispositivos es bueno tener alguna forma de diferenciar los diferentes dispositivos. Este valor, que se asigna a los dispositivos o terminales que acceden a la plataforma permiten informar al RESTful que plataforma está realizando la llamada.
  • x-auth-key: En aquellas APIs en las que se necesita autenticación de usuarios, esta clave suele albergar el hash que indica que el usuario se ha logeado correctamente y qué usuario es dentro de la plataforma.
  • x-ver: Es normal que las APIs evolucionen con el tiempo, al dar servicios a proyectos de terceros, también es habitual que tiendan a mantener versiones antiguas a la par que las nuevas, dando tiempo así a las aplicaciones de terceros a adaptar sus proyectos. Para gestionar esto, lo mejor es indicar mediante las cabeceras, que versión se está usando en cada momento.

Lógicamente, el uso de estas variables es totalmente subjetivo, se puede usar x-api-key, api_key, apikey,, authentication o cualquier nombre que encaje con las necesidades del webservice, aunque se suele añadir el “x-” como indicativo de variables específicas de dicho webservice.

En cuanto a la seguridad del API, hay que entender que el enviar toda esta información en “blanco” es bastante inseguro, pudiendo robar información sensible muy fácilmente, por lo que es necesario que toda comunicación con el webservice se realice siempre bajo protocolos seguros y certificados, en este caso bajo protocolos HTTPS.

 

You may also like

Uso de cookies

Este sitio web utiliza cookies para que usted tenga la mejor experiencia de usuario. Si continúa navegando está dando su consentimiento para la aceptación de las mencionadas cookies y la aceptación de nuestra política de cookies, pinche el enlace para mayor información.

ACEPTAR
Aviso de cookies