Consejos y mejores prácticas de desarrollo de API REST - Parte 1

INTRODUCCIÓN

Las API REST están en todas partes estos días. Si está desarrollando aplicaciones habilitadas para la red, es probable que haya consumido al menos una en su código y es muy posible que esté leyendo esto porque está a punto de escribir una propia.

Qué es esta serie y qué no es

Se asume que tiene una comprensión clara de lo que es REST y lo que pretende lograr. Tampoco es de ninguna manera un artículo completo de mejores prácticas sobre diseño y desarrollo de API web . Hay muchos de los que ya están disponibles en línea, y le sugiero que lea todos los que pueda.

Lo que es principalmente es una lista de errores muy comunes y a menudo pasados ​​por alto que las personas cometen al diseñar e implementar API REST. Lo sé, no solo porque los he encontrado en las API de otras personas, sino porque he creado algunos de ellos yo mismo. :)

Por que esto fue escrito

En un mundo perfecto, lo primero que cualquiera debería hacer después de desarrollar una API REST es escribir una aplicación cliente para ella. No estoy hablando de una interfaz de usuario con una lista de puntos finales a los que la gente puede llamar, en lugar de un caso de uso real de su API. No hay nada más revelador para revelar las ineficiencias de su creación, que tener que usarlo correctamente usted mismo. Lo sé porque he tenido que hacerlo decenas de veces.

Nuestro mundo no es perfecto, por supuesto, y la mayoría de las veces un desarrollador de backEnd tiene que pasar a otras cosas después de haber terminado con la implementación de la API, pero solo hasta que los consumidores de la API tengan que convocarlo para reparar su pecados. También he estado en esa posición infeliz muchas veces, así que espero que mis errores y consejos te ayuden a ahorrar tiempo, para que no tengas que volver a tu código API hasta que sea el momento de agregar nuevas funciones.

PLANIFICACIÓN

1. Antes de empezar

¡Estudie todos los libros y documentos de diseño y desarrollo de API REST que pueda encontrar! No mencionaré consejos comunes aquí, como usar sustantivos en lugar de verbos URI (vaya, acabo de hacerlo ...), etc., pero eso se debe a que supongo que ya ha leído sobre ellos en otra parte.

Considere alternativas

REST es bastante popular como paradigma, pero viene en muchos sabores . Antes de continuar, debería echar un vistazo a todos los que pueda. Mientras lo hace, no olvide verificar GraphQL , un enfoque completamente diferente, que no solo parece excelente para ciertos casos de uso, sino que también es utilizado por Facebook (quien lo desarrolló) y la nueva API v4 de GitHub .

Mira lo que otros han hecho

Eche un vistazo e intente utilizar tantas API populares, de organizaciones acreditadas, como pueda. Aquí hay algunos para comenzar: GitHub , Stripe , Twitter , PayPal

2. La Fundación

No asuma que su API seguirá siendo pequeña, casi nunca sucede. Incluso si es el único que lo usa para su propia aplicación cliente, muy pronto necesitará un punto final adicional, paginación, análisis, un modo de prueba y quién sabe qué más, y eso incluso antes de que su aplicación se vuelva popular y otras personas comiencen. solicitando acceso a su API…

OK, tal vez eso sea una exageración; pero como suele suceder en el desarrollo de software, si no establece una base sólida desde el principio, lo pagará caro a la larga. Dado que las API deben ser consistentes para ser fácilmente consumibles, tratar de agregarles funciones con cinta adhesiva no solo hará las cosas más difíciles para usted, sino también para sus clientes.

Además, cuanto mejor se hace para mantener las cosas limpias, menos tiempo se tarda en completarlas y muy pronto.

3. Especificación

Hablando de una base sólida; intente crear la especificación para su API antes de comenzar a escribir código. Sé que suena aburrido si no lo ha hecho antes, pero vale la pena a largo plazo y le ahorra mucho tiempo y molestias.

La especificación OpenAPI (OAS, anteriormente Swagger) parece ser la forma más popular de hacerlo en este momento, ya que cada vez más organizaciones y alternativas convergen en ella. Alternativamente, Postman es un excelente entorno de desarrollo de API pero solo es gratuito para individuos o pequeños equipos de desarrolladores.

Le sugiero encarecidamente que no ignore este consejo, a menos que esté desarrollando una pequeña API interna que solo usted consumirá.

4. Control de versiones

No me centraré en diferentes enfoques de control de versiones en esta publicación, ya que hay muchos recursos dedicados sobre este tema en línea. Solo intentaré resaltar lo importante que es que elijas un enfoque de control de versiones sólido y lo sigas religiosamente. También presentaré un enfoque que me ha sido de gran utilidad a lo largo de los años.

Por que es importante

Un enfoque de control de versiones sólido brinda tranquilidad a sus consumidores (y, por lo tanto, a sus usuarios finales) porque evita que los cambios de API perturben la funcionalidad de las aplicaciones cliente existentes. Incluso cuando las aplicaciones cliente son desarrolladas por el mismo desarrollador o la misma organización que la API, existen muchos escenarios en los que los clientes obsoletos pueden estar todavía en uso en el momento en que una actualización de la API está disponible.

Una ocurrencia muy común de este fenómeno son las aplicaciones cliente del sistema operativo móvil o de escritorio, donde los desarrolladores rara vez tienen el control total del ciclo de actualización. No importa qué tan buenos y automatizados sean los mecanismos de actualización de sus clientes, casi nunca puede estar 100% seguro de que sus usuarios estén ejecutando la última versión de sus aplicaciones cliente.

iOS tiene un mecanismo de actualización automática muy confiable para las aplicaciones habilitadas de forma predeterminada, sin embargo, dependiendo de las preferencias del usuario y el estado de la red, es posible que su dispositivo no haya tenido la oportunidad de actualizar su aplicación cliente la próxima vez que se ejecute. Lo mismo es cierto para las versiones más nuevas de Android, mientras que las versiones más antiguas tienen aún más probabilidades de quedarse atrás en las actualizaciones de aplicaciones.

Las aplicaciones de escritorio, por otro lado, pueden o no proporcionar un mecanismo de actualización automática, pero la mayoría de las veces son opcionales y siempre hay casos (como entornos empresariales) que no permiten actualizaciones inmediatas. Incluso las aplicaciones cliente del navegador podrían (y en la mayoría de los casos deberían) estar desacopladas de su backend y, por lo tanto, tener un ciclo de lanzamiento completamente diferente al de la API.

Comunique los cambios a sus consumidores

Incluso si tiene la API perfecta con el mejor sistema de control de versiones, todo no significa nada si sus consumidores no son conscientes de todo su potencial. Comunicar los cambios y las nuevas funciones es fundamental para que sus usuarios puedan aprovecharlos al máximo. Aún más importante es advertir a sus usuarios con suficiente anticipación sobre aspectos que van a quedar obsoletos o eliminados, para que tengan tiempo suficiente para actualizar, probar y enviar nuevas versiones de sus clientes.

Mantener una documentación actualizada y publicar registros de cambios detallados para cada versión es de suma importancia y debe ser parte de su ciclo de desarrollo.

Enfoque de versión mayor/menor

Un enfoque de control de versiones que he llegado a apreciar mucho a lo largo de los años es un esquema de versión mayor/menor. Su API se caracteriza por un número de versión principal, que (si hace las cosas bien) se actualiza solo cuando hay cambios importantes, y un número de versión menor, que se actualiza cada vez que hay pequeñas adiciones incrementales.

Visto desde otro ángulo, cada versión principal garantiza que la estructura de los recursos y el esquema de la API no se romperán durante la duración de su ciclo de vida, sin importar cuántas versiones secundarias se publiquen mientras tanto. Las versiones menores son compatibles con versiones anteriores.

Es común que la versión principal sea parte de la URL base de la API (por ejemplo, https://api.myserver.com/v1/endpoint ) y que la versión secundaria se pueda seleccionar mediante un encabezado de solicitud. Cuando no se proporciona el encabezado de la solicitud, se utiliza la última versión secundaria. Hay muchas API populares que siguen este enfoque, y mi favorita es Stripe (que usa fechas de lanzamiento para versiones menores).

Depende de usted elegir su propio sistema de control de versiones formal que funcione mejor para sus requisitos. Solo recuerda que una vez que lo hagas, tendrás que comprometerte con él.

5. Prueba

Como parte integral del proceso de desarrollo de software en general, las pruebas son esenciales para su API. Dado que las API suelen servir como enlace entre la única fuente de la verdad que es el servidor y una o más aplicaciones cliente, tienen que ser fiables en todas las circunstancias y no pueden permitirse el lujo de entrar en producción interrumpidas de ninguna manera. Además, dado que generalmente están expuestos a la web y, por lo tanto, son vulnerables a una gran cantidad de riesgos, deben probarse a fondo para una gran cantidad de escenarios comunes y no tan comunes.

Las pruebas manuales al llamar a sus puntos finales a través de herramientas como Swagger, Postman o la consola REST, solo pueden ayudarlo durante los primeros pasos del desarrollo, cuando todavía está probando las diversas funciones fundamentales. Mantener un conjunto de pruebas automatizadas desde el principio marca una gran diferencia en la calidad del producto terminado.

Debido a su naturaleza, las API son candidatas ideales para las pruebas funcionales. La prueba unitaria de su implementación interna es muy importante (como lo es para cualquier otra pieza de software) pero, en mi opinión, probar funcionalmente una API y compararla con una caja negra proporciona mucho más valor por el tiempo que le dedicará.

Mantener una base de datos de prueba que pueda configurar y desmontar mientras realiza las pruebas es una parte esencial del proceso. Siga agregando datos que hayan contribuido a problemas pasados ​​(observados durante el desarrollo o informados por sus consumidores) y enriquezca su conjunto de pruebas con pruebas de regresión para asegurarse de que se ha deshecho de esos errores de una vez por todas.

Nunca asuma que su validación de los parámetros de entrada está completa hasta que haya probado incluso los casos extremos más extraños (no olvide que sus aplicaciones cliente pueden tener bastantes errores). Finalmente, invierta tiempo en una infraestructura de registro adecuada para detectar esos pocos errores de tiempo de ejecución restantes, observar el comportamiento del consumidor y utilizar esa información para crear aún más escenarios de prueba.

6. Despliegue

Como ya habrás notado (o notarás a medida que sigas leyendo), esta publicación se centra en gran medida en cómo crear una API que no rompa las cosas. La fase más aterradora para romper cosas en casi todos los productos de software es, por supuesto, la implementación.

En la mayoría de los casos, si ha realizado las pruebas y el control de versiones correctamente, las posibilidades de encontrar un problema durante la implementación son muy bajas; sin embargo, aquí hay un par de consejos que pueden ser de ayuda adicional.

Desacoplar todo

Aquí hay un escenario muy común:

Su API proporciona datos a un par de clientes B2B desarrollados por organizaciones externas, sirve a un par de aplicaciones móviles y una aplicación web desarrollada por su propia organización, y es una parte integral de una aplicación de servidor, que también es accesible a través de la web. , para fines administrativos.

Eso puede parecer complicado, pero lo he visto muchas veces en el pasado en variaciones más simples o más complejas. El punto clave aquí es que la API, aunque es la piedra angular de una organización, a menudo está estrechamente relacionada con al menos una aplicación de servidor que tiene otras responsabilidades.

Eso significa que cuando llega el momento de actualizar la aplicación del servidor, si algo se rompe, es muy probable que la API también se rompa. Si eso sucede, la API derribará a todos sus consumidores con ella y, finalmente, la ira de los usuarios finales descenderá sobre la empresa.

Otra deficiencia del acoplamiento estrecho en este contexto es que el ciclo de lanzamiento de una aplicación afecta a todas las demás. Eso requerirá una planificación y organización complejas de implementaciones. Además, no tiene sentido desde un punto de vista comercial (cada aplicación debe lanzarse en su momento oportuno, sin afectar al resto).

Si su API y el resto de sus aplicaciones se desarrollan como módulos independientes de su infraestructura, todo esto desaparece. Alguien podría argumentar que tener más módulos separados significa más puntos de falla, pero eso puede resolverse con versiones y pruebas adecuadas. Además, incluso si la nueva versión de su API se rompe en el momento de la implementación, su equipo será el primero en saberlo. En este caso, si no se puede hacer nada mejor, siempre puede retrasar los lanzamientos de sus clientes un par de días hasta que esté seguro de que todo funciona correctamente.

Un caso peligroso del que debe protegerse con pruebas rigurosas es cuando la nueva versión de su aplicación de servidor rompe la versión existente de su API. Nuevamente, la única forma de evitar esto es (por supuesto) a través de un estricto proceso de desarrollo con versiones y pruebas adecuadas. Tratar todas las partes de su infraestructura como módulos distintos fomenta ese enfoque aún más.

7. (Agraciado) Deprecación

En algún momento, a medida que su aplicación madure, es inevitable que tenga que desaprobar su versión principal actual de la API en favor de una nueva. Las aplicaciones cliente que aún están en desarrollo también tendrán que actualizarse a la nueva versión, pero eso puede llevar tiempo.

Además, hay casos en los que incluso la acción inmediata de los desarrolladores no significa actualizaciones inmediatas de las aplicaciones cliente. Si bien las versiones actualizadas de las aplicaciones web pueden estar disponibles para los usuarios finales tan pronto como se publiquen, las versiones anteriores de las aplicaciones de sistemas operativos móviles y nativos tienden a permanecer durante mucho tiempo. Algunos usuarios realmente no comprenden (o ni siquiera son conscientes de) el proceso de actualización de aplicaciones en su teléfono o computadora. Si esas aplicaciones de repente comienzan a funcionar mal, la respuesta de los usuarios podría ser simplemente dejar de usarlas.

La obsolescencia de una versión principal de la API no debería significar la interrupción del servicio. La versión obsoleta debería seguir funcionando exactamente como lo hizo, durante un período de tiempo (el mayor tiempo posible) que se comunicará de forma clara y repetida (a medida que se acerque a su final) a sus consumidores. Idealmente, las versiones anteriores de su API nunca deberían dejar de funcionar, a menos que representen un riesgo de seguridad o estén causando daños a su backend.

8. Buenas prácticas a menudo ignoradas

Puede usar formas plurales o singulares para los recursos, pero no ambas

/cars está bien y también lo está /car, pero no puede usar ambos. Elija un formulario y cúmplalo en toda tu API. Si no lo hace, estará confundiendo a sus consumidores y tal vez incluso a sus propios desarrolladores oa usted mismo en el futuro.

Devolver objetos actualizados en las respuestas PUT y PATCH

Después de una solicitud exitosa a través de los verbos PUT o PATCH, el cliente generalmente necesita conocer el estado del recurso actualizado. Dado que es muy posible que varios clientes lo estén actualizando al mismo tiempo, esta es la única forma de mantener a cada uno informado sobre el estado del recurso en el momento en que se realizó la actualización.

Cookies y PHPSESSIONID

Éste es muy común en aplicaciones desarrolladas con PHP. La API usa su propio token de autenticación personalizado, pero sin el conocimiento del desarrollador que usa el manejo de sesión predeterminado de PHP, ¡todas las respuestas también incluyen la temida cookie PHPSESSIONID! Esto provoca todo tipo de errores a largo plazo, porque nadie (incluido el desarrollador) está informado sobre la cookie, porque nadie cree que la hayan puesto allí.

Las cookies, en general, no están explícitamente prohibidas por REST. Pueden causar problemas si se usan incorrectamente (por ejemplo, si intenta acceder a un dominio separado que también debería estar autorizado a través de su mecanismo de API), pero no están prohibidos por ninguna especificación. Sin embargo, lo que debe evitarse es utilizar más de una forma de autenticación al mismo tiempo.

Con respecto al manejo de la sesión de PHP, nunca debe confiar en el enfoque de cookies PHP predeterminado para su API, a menos que desee que la cookie PHPSESSIONID actúe como el token de autenticación de su API (¡que no recomiendo de ninguna manera!). Mi consejo sería implementar un mecanismo de manejo de sesiones personalizado que implemente su método de autenticación preferido.

No exponga errores internos ni detalles de implementación

A lo largo de los años, he visto esto en innumerables ocasiones, incluso en API populares de grandes empresas. ¡No es bueno exponer errores internos (como SQL) en sus respuestas! Encuentre una manera confiable de registrarlos para referencia futura, pero tradúzcalos a un 500 - Error interno del servidor genérico en sus respuestas de API.