Representational state transfer (REST) es un estilo de arquitectura de software que se usa para crear aplicaciones de servicios web. Un servicio web que sigue estas pautas se denomina RESTful. Dicho servicio debe proporcionar recursos web en un conjunto predefinido de operaciones con un protocolo sin estado.
 

Condiciones que debe cumplir

Cliente-servidor: aplicación de cliente y aplicación de servidor. Se trata de la separación de responsabilidades, con ello mejoramos la portabilidad y la escalabilidad porque permite que esos componentes evolucionen de forma independiente.

Sin estado: cada solicitud de un cliente al servidor debe contener toda la información necesaria, incluidos los detalles de autenticación, el servidor no puede almacenar nada sobre solicitudes, sesiones, historial, etc.

Caché: cuando los datos de las posibles respuestas deben almacenarse en caché, los clientes tienen derecho a reutilizar los datos de las respuestas más adelante. Esto mejorará la eficiencia y la escalabilidad, pero se debe tomar en cuenta que puede disminuir la confiabilidad si los datos almacenados en caché difieren significativamente de los datos en el servidor.

Interfaz uniforme: definir y mantener los estándares de la interfaz API, por ejemplo, identificación de recursos y mensajes de respuesta. Si usas los nombres de recursos en plural, debes seguir este estándar en todos los URI, mejorará la legibilidad y la capacidad de mantenimiento.

Sistema en capas: el sistema debe estar compuesto por componentes en capas jerárquicas, cada componente solo es consciente de la capa inmediata con la que están interactuando. Por ejemplo, un sistema puede tener una capa de datos, una capa de caché, una capa de seguridad, etc. Y todas esas capas no deberían afectar la comunicación entre el servidor y el cliente.

Código bajo demanda: esta es la única condición opcional, el servidor proporcionará representaciones estáticas de los recursos, pero cuando se le solicite, puede enviar código ejecutable.
 

Mejores prácticas para diseñar una interface de API uniforme

REST se aplica con frecuencia en aplicaciones web y aprovecha el protocolo HTTP, mas no se limita a ello. Una API RESTful expondrá los recursos de la aplicación a través de un grupo de identificadores uniformes de recursos (URI). Las respuestas que devolverá serán en JSON o XML, incluso ambos, dando la opción que el cliente elija el tipo de respuesta usando el encabezado de tipo de contenido. Una vez definidos los recursos de la aplicación, es hora de elegir una estrategia de nomenclatura de recursos y combinarla con los métodos HTTP para representar operaciones en esos recursos.

Es importante definir estándares para las respuestas. En la fase de diseño de la API debemos tener en cuenta las siguientes preguntas:

• ¿Cuál será el organismo de respuesta en caso de falla?
• ¿Tendrá un mensaje que describa el error, solo un código de referencia o ambos?
• En caso de éxito, ¿Qué datos de recursos se presentarán?
• ¿Qué códigos de respuesta HTTP se utilizarán en cada respuesta?

Vamos a ver varios ejemplos para aclarar esas dudas.
 

Usar sustantivos para representar recursos, no acciones

Imaginemos que tenemos una API para consultar libros, con una url definida «api.mipagina.com» y tenemos una idea Errónea de escribir la acción en la url «https://api.mipagina.com/obtener-libros», debemos evitar ese modo de trabajo, la acción «obtener» debería definirse por el tipo de método HTTP.

https://api.mipagina.com/libros

Por defecto consultamos dicha url con un simple get para obtener información. Es un estándar para API Rest.

Si decidimos usar el plural «libros», debemos obligar a que todos los recursos de la aplicación estén en plural, para evitar confusiones y mantener el estándar.
 

Usar la relación jerárquica entre recursos

Si necesitamos consultar detalles de los libros, como, por ejemplo, consultar por autor, podríamos generar las URI de esta manera:

La idea es mantener una coherencia que se haga fácil entender a qué se refiere cada acción. Adicional para mantener la legibilidad, establecemos el estándar:

• Utilizar guiones (-) en vez de guiones bajos (_)
• Utilizar solo minúsculas
• No usar extensiones de archivo (.jsp,.php,.html, etc)

Usar métodos HTTP para indicar operaciones en recursos

Los más comunes son para operaciones CRUD:

• POST: Crear recursos
• GET: Leer recursos
• PUT: Actualizar o reemplazar recursos
• PATCH: Modificar recursos
• DELETE: Eliminar recurso

Ejemplos

Como se visualiza en el ejemplo, mantenemos el texto en la URL uniforme y cada acción se indica por el verbo del método HTTP.
 

Usar códigos de respuesta HTTP adecuados

Teniendo en cuenta el tipo de código que devuelve la respuesta, podemos establecer los más comunes para indicar:

• 200 OK: Indica éxito.
• 201 Creado: La creación se realizó correctamente (a través de POST o PUT).
• 204 Sin contenido: Indica éxito sin una respuesta, se usa comúnmente para solicitudes DELETE y PUT.
• 400 Solicitud incorrecta: Indica que algo no está bien con la solicitud, por ejemplo, información faltante o datos no válidos.
• 401 No autorizado: Indica credenciales de autenticación no válidas.
• 403 Prohibido: Usuario no autorizado para realizar la operación.
• 404 No encontrado: Recurso no encontrado.
• 405 Método no permitido: Indica que existe una URL, pero el método HTTP no es aplicable.
• 500 Error interno: Indica que el servidor encontró un error y no sabe cómo manejarlo.

Tomando en cuenta que no tienes que configurarlos todos, lo común es establecer el 200, 201 para modo de confirmación en tu api y otros se pueden obviar o dejar que el propio servidor los maneje automáticamente.

Si estás trabajando en una organización seguramente ya tienen sus estándares, sino, puedes aplicar estos estándares en tus proyectos.