La guía (algo) definitiva para crear mejores API Foto de en Marius Masalar 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 (clave del éxito) Jeff Bezos Es posible que algunos de ustedes ya estén al tanto del mandato de para los desarrolladores de Amazon. Si nunca tuvo la oportunidad de escucharlo, los siguientes puntos son el quid de la cuestión: Jeff Bezos De ahora en adelante, todos los equipos expondrán sus datos y funciones a través de las interfaces de servicio. Los equipos deben comunicarse entre sí a través de estas interfaces. 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. No importa qué tecnología utilicen. HTTP, Corba, Pubsub, protocolos personalizados, no importa. A Bezos no le importa. 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. 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: : para obtener un recurso o una colección de recursos. GET : para crear un recurso o una colección de recursos. POST : para actualizar el recurso existente o la colección de recursos. PUT/PATCH : para eliminar el recurso existente o la colección de recursos. ELIMINAR 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. debe preferirse a /products?name='ABC' /getProductsByName debe preferirse a /products?type='xyz' /getProductsByType De esta manera, puede evitar las URL largas con un diseño simple. Utilice códigos HTTP adecuados Tenemos un . 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. montón de códigos HTTP : este es el código HTTP más utilizado para mostrar que la operación realizada se realizó correctamente. 200 OK : esto se puede usar cuando usa el método POST para crear un nuevo recurso. 201 CREADO : se puede usar para reconocer la solicitud enviada al servidor. 202 ACEPTADO : se puede usar cuando falla la validación de entrada del lado del cliente. 400 SOLICITUD INCORRECTA : se puede utilizar si el usuario o el sistema no están autorizados para realizar determinadas operaciones. 401 NO AUTORIZADO / 403 PROHIBIDO : se puede usar si está buscando cierto recurso y no está disponible en el sistema. 404 NO ENCONTRADO : esto nunca debe lanzarse explícitamente, pero puede ocurrir si el sistema falla. 500 ERROR INTERNO DEL SERVIDOR : se puede usar si el servidor recibió una respuesta no válida del servidor ascendente. 502 BAD GATEWAY 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 , 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. /v1.2/products 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 y . Por ejemplo, También se recomienda mantener un límite predeterminado y una compensación predeterminada. limit offset /products?limit=25&offset=50 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 puede ser útil. Open API le permite diseñar sus API primero y compartirlas con los consumidores de una manera más fácil. la especificación OpenAPI 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 _Nuestra comunidad publica historias que vale la pena leer sobre las últimas tendencias y aprendizajes tecnológicos. ¡Únete!_stuff.technology 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 por la información. Sébastien D.
