API REST Design: 7 consejos esenciales

API REST diseño en su mejor versión

*actualizado en 31 de marzo de 2020

El diseño de una API REST no es más que la creación de una interfaz con reglas bien definidas, puesta a disposición para que se pueda interactuar con un sistema y obtener su información o realizar operaciones.Es como expliqué allí en los artículos sobre Qué son las APIs: su interfaz debe funcionar como un camarero en un restaurante: recibiendo sus pedidos y devolviendo los recursos (o platos), sin que los clientes tengan que visitar la cocina para recoger el plato allí.

En este post, conoceremos algunos consejos para crear un diseño mejorado y estandarizado de lo que llamamos una verdadera API en el estándar RESTful.

Y, por supuesto, siempre es bueno tener en cuenta que, al diseñar tu API REST, también debes tener en cuenta quién la utilizará, cómo se utilizará dentro de tu estrategia y también cómo se expondrá al mundo. Este razonamiento, el de situar la API en un lugar privilegiado en tu planificación, se denomina API First.

Usar sustantivos y no verbos

Uno de los principales fallos de estandarización a la hora de crear APIs RESTful está relacionado con el patrón de los endpoints creados (URLs de acceso al servicio). El estándar RESTful exige el uso de sustantivos, no de verbos o nombres de métodos. Por ejemplo:

/getAllCustomers/createNewCustomer/eliminarCustomer

Son formas incorrectas de nomenclatura, que se asemejan a las funciones de algún lenguaje de programación orientado a objetos. En su lugar, para el Diseño más apropiado, utilice sustantivos, como:

/clientes/clientes/563

Utilizar correctamente los métodos HTTP

El principio fundamental de REST es separar su API en recursos lógicos. Estos recursos se manipulan mediante peticiones HTTP con métodos GET, POST, PUT y DELETE.

Por ejemplo, cuando se hace una petición al recurso /clientes/563 utilizando el método GET, se está solicitando que se recupere un cliente específico con el código 563.

Del mismo modo, cuando realice la misma petición (es decir, en el endpoint /clientes/536) utilizando el método DELETE, estará realizando una exclusión específica del cliente, el código 563.

Utilizar los nombres en plural

¿El nombre del punto final debe estar en singular o en plural?

Esta es una pregunta que suele generar mucha discusión en el Diseño de APIs RESTful.

En general, la elección depende de ti. En particular, prefiero los nombres en plural, ya que indican un conjunto de características (como en el caso de los clientes, más arriba).Sin embargo, una cosa es cierta: no mezcles puntos finales en singular y en plural.

La recomendación es que simplifiques y utilices todos los nombres en plural.

Utilizar sub-recursos para las relaciones

Hay situaciones en las que un recurso está relacionado con otro. Esto es habitual cuando existe una jerarquía de objetos y recursos.

Por ejemplo, si se tratara de una API que devolviera datos estadísticos sobre la geografía de un país, podría haber sub-recursos para los estados dentro del país y los municipios dentro de los estados.

Cuando proceda, utilice sub-recursos en los puntos finales.

Por ejemplo, la solicitud

GET /clientes/231/proyectos/

debe volver a la lista de proyectos del cliente 231. Y la solicitud

GET /clientes/231/proyectos/4

debe volver al proyecto nº 4 del cliente 231.

No cambiar de estado con el método GET

Cuando se realizan operaciones que cambian el estado de un objeto, se utilizan los métodos POST, PUT y DELETE.

El método GET, como se intuye por su nombre, debe devolver sólo una versión de lectura del recurso.

HTTP ofrece otros métodos para escribir en los recursos, así que utilízalos adecuadamente. En este punto, es importante recordar los permisos y cuestiones de seguridad de la API, lo que nos lleva a nuestro siguiente tema:

Utilizar el cifrado SSL

Su API RESTful debe utilizar necesariamente el cifrado SSL.

Dado que se puede acceder a la web de su API desde cualquier lugar con acceso a Internet, como el patio de comidas de un centro comercial, una librería, una cafetería o un aeropuerto, su preocupación es garantizar un acceso seguro a los datos y servicios que ofrece su API.

Sin embargo, no todos estos lugares ofrecen un acceso seguro y cifrado.

Tener la información que llevas encriptada es esencial. Además, el uso de SSL con tokens facilita la autenticación entre solicitudes, evitando que cada una de ellas tenga que volver a autenticarse.

Crear versiones para su API

Como todo software, las APIs deben crecer y evolucionar. Por muy cuidadoso y experimentado que sea, su API no será perfecta en la primera versión.

Y no tiene por qué serlo.

A menudo, es mejor exponer la primera versión de tu API y hacerla evolucionar gradualmente. Sin embargo, ten cuidado de no cambiar demasiado su diseño y acabar rompiendo las aplicaciones que utilizaban las versiones anteriores(como dijo Jeremiah Lee, de Fitbit, en la entrevista a Kleber, nuestro CEO).

Por lo tanto, al crear una nueva versión para su API, asegúrese de que la versión anterior sigue estando disponible, para no romper la funcionalidad del sistema. Tras comunicar los cambios a los desarrolladores, y darles tiempo para que se adapten, las versiones antiguas pueden ser descatalogadas, o puedes mantenerlas en el aire, sin ofrecerles soporte.

Asegure el éxito de su API RESTful!

Los 7 pasos detallados anteriormente garantizarán que la onboarding (desarrolladores que comienzan a utilizar su API) de su API sea mucho más fácil.

Un último consejo es que vigiles la usabilidad de tu API. Consulta el artículo Cómo medir la usabilidad de una API.

‍