Diseño de API RESTful: guía paso a paso

La guía (algo) definitiva para crear mejores API

Foto de Marius Masalar en Unsplash

Como desarrolladores de software, la mayoría de nosotros usamos o creamos API REST en el día a día. Las API son los medios predeterminados de comunicación entre los sistemas. Amazon es el mejor ejemplo de cómo las API se pueden usar de manera eficiente para la comunicación. En este artículo, voy a hablar sobre cómo diseñar mejor sus API RESTful para evitar errores comunes.

Mandato de Jeff Bezos (clave del éxito)

Es posible que algunos de ustedes ya estén al tanto del mandato de Jeff Bezos para los desarrolladores de Amazon. Si nunca tuvo la oportunidad de escucharlo, los siguientes puntos son el quid de la cuestión:

1. De ahora en adelante, todos los equipos expondrán sus datos y funciones a través de las interfaces de servicio.
2. Los equipos deben comunicarse entre sí a través de estas interfaces.
3. No se permitirá ninguna otra forma de comunicación entre procesos: ningún enlace directo, ninguna lectura directa del almacén de datos de otro equipo, ningún modelo de memoria compartida, ningún tipo de puertas traseras. La única comunicación permitida es a través de llamadas de interfaz de servicio a través de la red.
4. No importa qué tecnología utilicen. HTTP, Corba, Pubsub, protocolos personalizados, no importa. A Bezos no le importa.
5. Todas las interfaces de servicio, sin excepción, deben diseñarse desde cero para que sean externalizables. Es decir, el equipo debe planificar y diseñar para poder exponer la interfaz a los desarrolladores en el mundo exterior. Sin excepciones.
6. Cualquiera que no haga esto será despedido.

Finalmente, esto se convirtió en la clave del éxito de Amazon. Amazon podría construir sistemas escalables y luego también podría ofrecerlos como servicios como Amazon Web Services .

Principios de diseño de API RESTful

Ahora comprendamos los principios que debemos seguir al diseñar las API RESTful:

Mantenlo simple

Fuente — Internet

Necesitamos asegurarnos de que la URL base de la API sea simple. Por ejemplo, si queremos diseñar API para productos, debe diseñarse como:

/productos/productos/12345

La primera API es para obtener todos los productos y la segunda es para obtener un producto específico.

Usa sustantivos y NO los verbos

Muchos desarrolladores cometen este error. Por lo general, olvidan que tenemos métodos HTTP para describir mejor las API y terminan usando verbos en las URL de las API. Por ejemplo, la API para obtener todos los productos debe ser

/productos

y NO como se muestra a continuación

/getAllProducts

Algunos patrones de URL comunes que he visto hasta ahora

Uso de métodos HTTP correctos

Las API RESTful tienen varios métodos para indicar el tipo de operación que vamos a realizar con esta API:

• GET : para obtener un recurso o una colección de recursos.
• POST : para crear un recurso o una colección de recursos.
• PUT/PATCH : para actualizar el recurso existente o la colección de recursos.
• ELIMINAR : para eliminar el recurso existente o la colección de recursos.

Necesitamos asegurarnos de que usamos el método HTTP correcto para la operación dada.

Usar plurales

Este tema es un poco discutible. A algunas personas les gusta mantener la URL del recurso con nombres en plural, mientras que a otras les gusta mantenerla en singular. Por ejemplo -

/productos

/producto

Me gusta mantenerlo en plural, ya que evita la confusión si estamos hablando de obtener un solo recurso o una colección. También evita agregar cosas adicionales como adjuntar todo a la URL base, por ejemplo /product/all

Puede que a algunas personas no les guste esto, pero mi única sugerencia es mantener la uniformidad en todo el proyecto.

Usar parámetros

En algún momento necesitamos tener una API que debería contar más historias que solo la identificación. Aquí deberíamos hacer uso de los parámetros de consulta para diseñar la API.

• /products?name='ABC' debe preferirse a /getProductsByName
• /products?type='xyz' debe preferirse a /getProductsByType

De esta manera, puede evitar las URL largas con un diseño simple.

Utilice códigos HTTP adecuados

Tenemos un montón de códigos HTTP . La mayoría de nosotros solo terminamos usando dos: ¡200 y 500! Esto ciertamente no es una buena práctica. Los siguientes son algunos códigos HTTP de uso común.

• 200 OK : este es el código HTTP más utilizado para mostrar que la operación realizada se realizó correctamente.
• 201 CREADO : esto se puede usar cuando usa el método POST para crear un nuevo recurso.
• 202 ACEPTADO : se puede usar para reconocer la solicitud enviada al servidor.
• 400 SOLICITUD INCORRECTA : se puede usar cuando falla la validación de entrada del lado del cliente.
• 401 NO AUTORIZADO / 403 PROHIBIDO : se puede utilizar si el usuario o el sistema no están autorizados para realizar determinadas operaciones.
• 404 NO ENCONTRADO : se puede usar si está buscando cierto recurso y no está disponible en el sistema.
• 500 ERROR INTERNO DEL SERVIDOR : esto nunca debe lanzarse explícitamente, pero puede ocurrir si el sistema falla.
• 502 BAD GATEWAY : se puede usar si el servidor recibió una respuesta no válida del servidor ascendente.

Versionado

El control de versiones de las API es muy importante. Muchas compañías diferentes usan versiones de diferentes maneras, algunas usan versiones como fechas mientras que otras usan versiones como parámetros de consulta. Por lo general, me gusta mantenerlo como prefijo al recurso. Por ejemplo -

/v1/productos/v2/productos

También me gustaría evitar el uso de /v1.2/products , ya que implica que la API cambiaría con frecuencia. Además, es posible que los puntos (.) no se vean fácilmente en las URL. Así que mantenlo simple.

Siempre es una buena práctica mantener la compatibilidad con versiones anteriores para que, si cambia la versión de la API, los consumidores tengan tiempo suficiente para pasar a la siguiente versión.

Usar paginación

El uso de la paginación es imprescindible cuando expone una API que podría devolver una gran cantidad de datos y, si no se realiza un equilibrio de carga adecuado, el consumidor podría terminar desactivando el servicio.

Siempre debemos tener en cuenta que el diseño de la API debe ser a prueba de errores.

Aquí se recomienda el uso de limit y offset . Por ejemplo, /products?limit=25&offset=50 También se recomienda mantener un límite predeterminado y una compensación predeterminada.

Formatos compatibles

También es importante elegir cómo responde tu API. La mayoría de las aplicaciones modernas deberían devolver respuestas JSON, a menos que tenga una aplicación heredada que aún necesite obtener una respuesta XML.

Utilice mensajes de error adecuados

Siempre es una buena práctica mantener un conjunto de mensajes de error que envía la aplicación y responder con la identificación adecuada. Por ejemplo, si usa las API de gráficos de Facebook, en caso de errores, devuelve un mensaje como este:

{"error": {"mensaje": "(#803) Algunos de los alias que solicitó no existen: productos","tipo": "OAuthException","código": 803,"fbtrace_id": "FOXX2AhLh80"} }

También he visto algunos ejemplos en los que las personas devuelven la URL con un mensaje de error que le brinda más información sobre el mensaje de error y cómo manejarlo también.

Uso de especificaciones API abiertas

Para que todos los equipos de su empresa cumplan con ciertos principios, el uso de la especificación OpenAPI puede ser útil. Open API le permite diseñar sus API primero y compartirlas con los consumidores de una manera más fácil.

Conclusión

Es bastante evidente que si desea comunicarse mejor, las API son el camino a seguir. Pero si están mal diseñados, podría aumentar la confusión. Por lo tanto, esfuércese por diseñar bien y el resto es solo la implementación.

Gracias por leer

Si encontró algunas formas mejores de diseñar API, no dude en compartirlas en la sección de comentarios. ¡Todos los comentarios son bienvenidos! Para más historias de este tipo, siga STUFF.TECHNOLOGY

stuff.technology _Nuestra comunidad publica historias que vale la pena leer sobre las últimas tendencias y aprendizajes tecnológicos. ¡Únete!_stuff.technology

Editar -

Otra gran lectura sobre la guía de diseño utilizada en el Banco Nacional de Bélgica: https://opensource.nbb.be/posts/002-restful-api-design-guide/

Gracias a Sébastien D. por la información.