Restful APIs – ¿Que es REST?

REST, REpresentational State Transfer, es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP, de ese modo podemos crear APIs que pueden ser usadas por cualquier dispositivo o cliente que entienda HTTP.

Debemos tener dos cosas en cuenta a la hora de desarrollar una API REST, el uso correcto de URIs y el uso correcto de HTTP.

Ademas de esto, nunca se debe guardar estado en el servidor, toda la información que se requiere para mostrar el resultado debe estar en la consulta por parte del cliente. Esto es, nada de variables de sesión en el servidor.

Uso correcto de URIs

Las URL (Uniform Resource Locator), son un tipo de URI (Uniform Resource Identifier) que nos permite identificar de forma única un recurso.

Cada URL de nuestra API es un recurso, ya sean datos o archivos.

La estructura básica de cada URL seria la siguiente:

Existen varias reglas básicas para ponerle nombre a la URI de un recurso:

  • Los nombres de URI no deben implicar una acción, por lo tanto debe evitarse usar verbos en ellos – Por ejemplo /productos/4/editar seria incorrecto ya que usamos el verbo “editar”, la URI correcta seria /productos/4 independientemente de si vamos a ver, editar o borrar.
  • Deben ser únicas, no debemos tener más de una URI para identificar un mismo recurso.
  • Deben ser independiente de formato – Por ejemplo /productos/4.html seria incorrecto, se debe usar la misma URI ya sea html, txt, xml, o json.
  • Deben mantener una jerarquía lógica – Por ejemplo /productos/4/cestas/1 no seria correcto, ya que es el producto el que pertenece a la cesta, lo correcto seria /cestas/1/productos/4
  • Los filtrados de información de un recurso no se hacen en la URI – Para filtrar u ordenar debemos usar parámetros HTTP sobre la URI, por ejemplo /productos?orden=DESC&pagina=3

Uso correcto de HTTP

Conocer los métodos HTTP, códigos de estado y aceptación de contenidos es clave, con los métodos podemos realizar varias acciones sobre una misma URI:

  • GET: Para consultar y leer recursos – Ejemplo: GET /productos o GET /productos/4
  • POST: Para crear recursos – Ejemplo: POST /productos
  • PUT: Para editar recursos – Ejemplo: PUT/productos/4
  • DELETE: Para eliminar recursos – Ejemplo: DELETE/productos/4

Códigos de estado.

Cuando realizamos una operación, es vital saber si dicha operación se ha realizado con éxito o en caso contrario, por qué ha fallado.

Por ejemplo si una consulta tiene datos insuficientes no podemos devolver el resultado con estado 200, que significa que la operación se a realizado correctamente, independientemente de que usemos variables tipo “result: 0” o “success: false”.

Es muy importante conocer estos codigos y saber cuándo utilizarlos, asi lo correcto seria devolver el error anterior con el estado HTTP 400, solicitud incorrecta.

Del mismo modo debemos informar al cliente del formato de la respuesta mediante el header Content-Type, por ejemplo “application/pdf” para devolver un PDF.