4 características esenciales de las API exitosas

Si está creando una aplicación que utiliza alguna variación de un modelo de cliente/servidor, necesita una interfaz de programación de aplicaciones (API). Una API es un límite claramente definido entre un proceso y otro. Una limitación común en las aplicaciones web es una API REST/JSON.

Si bien los desarrolladores pueden concentrarse principalmente en el funcionamiento (u operación) de la API, existen algunos requisitos "no funcionales" que requieren su atención. cuatro debe tener los requisitos no funcionales para todas las API son:

  • Seguridad
  • Documentación
  • Validación
  • Prueba
Índice

    Seguridad

    La seguridad es un requisito esencial en el desarrollo de software. Hay cuatro áreas que los desarrolladores de API pueden incluir cuando se trata de seguridad:

    1. Certificados HTTPS/SSL
    2. Compartir recursos entre orígenes
    3. Autenticación y token web JSON
    4. Autorizaciones y alcances

    1. Certificados HTTPS/SSL

    El estándar de oro para la web es HTTPS, que utiliza SSL y ciframos puede ayudarte a lograr esto. Es una autoridad de certificación gratuita, automatizada y abierta del Grupo de Investigación de Seguridad de Internet (ISRG) sin fines de lucro.

    El software Let's Encrypt genera certificados de autoridad central para su dominio. Estos certificados garantizan que las cargas de datos de la API al cliente se cifren de un punto a otro.

    Let's Encrypt admite varias opciones de distribución para administrar certificados; revisa su documentación para encontrar la solución adecuada a sus necesidades.

    2. Compartir recursos entre orígenes

    CORS es una verificación previa de la política de seguridad específica del navegador. Si su servidor API no está en el mismo dominio que el dominio del cliente solicitante, deberá encargarse de CORS. Por ejemplo, si su servidor se está ejecutando api.dominio-a.com y recibe una solicitud de cliente de dominio-b.com, CORS envía una solicitud de verificación previa de HTTP para ver si su servicio API aceptará solicitudes del lado del cliente del dominio del cliente.

    Según MDN:

    "El uso compartido de recursos de origen cruzado (CORS) es un mecanismo basado en el encabezado HTTP que permite que un servidor indique cualquier otra fuente (dominio, esquema o puerto) distinta de la suya desde la cual un navegador debería permitir que se carguen los recursos".

    Hay muchas bibliotecas de soporte para Nodo.js a ayudar a los desarrolladores de API con CORS.

    3. Autenticación y token web JSON

    Existen varios enfoques para validar un usuario autenticado en la API, pero una de las mejores formas es usar JSON Web Tokens (JWT). Estos tokens se firman utilizando varios tipos de bibliotecas criptográficas conocidas.

    Cuando un cliente inicia sesión, un servicio de gestión de identidad proporciona al cliente un JWT. Luego, el cliente puede usar este token para realizar solicitudes a la API. La API tiene acceso a una clave pública o secreta que utiliza para verificar el token.

    Hay varias bibliotecas disponibles para ayudar a verificar tokens, incluyendo jsonwebtoken. Para obtener más información sobre JWT y las bibliotecas que lo admiten en cada idioma, consulte JWT.io.

    import jwt from 'jsonwebtoken'

    export default function (req, res, next) {
        // req.headers.authorization Bearer token
        const token = extractToken(req)
        jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {
            if (err) { next(err) }
            req.session = decoded
            next()
        })
    }

    4. Autorizaciones y alcances

    La autenticación (o verificación de identidad) es importante, pero también lo es la autorización, p. ¿El cliente verificado tiene el privilegio de realizar esta solicitud? Aquí es donde áreas son preciosos Cuando el cliente se autentica con el servidor de administración de identidades y se crea un token JWT, si el servicio de administración de identidades proporciona alcances para el cliente autenticado especificado, puede permitir que el servicio API determine si esta solicitud de cliente verificada se puede realizar sin tener que realizar una operación adicional. búsqueda costosa en una lista de control de acceso.

    Un alcance es un bloque de texto (generalmente delimitado por espacios) que describe la capacidad de acceso de un punto final de API. Normalmente, los alcances se dividen entre Recursos y Acciones. Este patrón funciona bien para las API REST/JSON, ya que están estructuradas de manera muy similar en formato RECURSO: ACCIÓN (por ejemplo, ARTÍCULO: ESCRIBIR o ARTÍCULO: LEER, donde ARTÍCULO es el recurso y LEER y ESCRIBIR son las acciones).

    Esto permite que la API se centre en la función y no en los roles o usuarios. El Servicio de administración de acceso a la identidad puede relacionar roles y usuarios con ámbitos y luego proporcionar los ámbitos al cliente en un JWT verificado.

    Resumen

    Al crear e implementar API, la seguridad siempre debe ser uno de los requisitos más importantes. Si bien la seguridad es un tema amplio, abordar estas cuatro áreas posicionará su API de manera óptima para los entornos de producción.

    Documentación

    ¿Qué es peor que la falta de documentación? Documentación desactualizada.

    Los desarrolladores tienen una relación de amor y odio con la documentación. Sin embargo, la documentación es una parte crucial para definir el éxito de una API. Los desarrolladores necesitan saber cómo usar la API, y la documentación que crea juega un papel muy importante en la educación de los desarrolladores sobre cómo usarla mejor.

    Hay tres áreas en las que centrarse en la documentación de la API:

    1. Incorporación de desarrolladores (LÉAME)
    2. Referencia técnica (especificaciones)
    3. Cómo usar (Primeros pasos y otras guías)

    1. Incorporación de desarrolladores

    Cuando crea un servicio de API, debe especificar cosas como: ¿Qué hace la API? ¿Cómo se configura un entorno de desarrollador? ¿Cómo probar el servicio? ¿Cómo se envía un problema? ¿Cómo lo distribuyes?

    La forma habitual de responder a estas preguntas es con un archivo README. Es el archivo en su repositorio de código que brinda a los desarrolladores un punto de partida para trabajar con su proyecto.

    Un LÉAME debe contener:

    • Una descripción de la API
    • Enlaces a referencias técnicas y guías.
    • Cómo configurar el proyecto como desarrollador
    • Cómo probar el proyecto
    • Cómo distribuir el proyecto
    • Gestión de dependencias
    • Guía de contribución
    • Código de conducta
    • Licencia
    • Gratitud

    Sea conciso en su LÉAME; no es necesario explicar todos los aspectos, pero proporcionar suficiente información para que los desarrolladores puedan aprender más a medida que se familiarizan con su proyecto.

    2. Referencia técnica

    En una API REST/JSON, cada punto final es una función específica con un propósito. Es importante tener documentación técnica que especifique cada punto final; define la descripción, entradas y salidas que pueden ocurrir; y proporciona ejemplos para varios clientes.

    REST/JSON tiene un estándar de especificación llamado API abierta, que puede guiarlo a través de los detalles necesarios para documentar una API. OpenAPI también puede generar documentación de presentación para su API.

    3. Uso

    Los usuarios de su API quieren algo más que especificaciones técnicas. Quieren saber cómo usar su API en situaciones o casos específicos. La mayoría de los usuarios potenciales tienen un problema y buscan su API para solucionarlo.

    Una excelente manera de presentar su API a los usuarios es con una página de "inicio". Esto puede guiarlo a través de un caso de uso simple que lo pone rápidamente al día con los beneficios de su API.

    Resumen

    La documentación es un componente clave de cualquier API exitosa. Al crear su documentación, piense en las tres áreas de enfoque (incorporación, técnica y uso) que cubren estas bases y tendrá una API bien documentada.

    Validación

    Uno de los aspectos más a menudo pasados ​​por alto del desarrollo de API es la validación. La validación es el proceso de verificar la entrada de fuentes externas. Estas fuentes pueden ser un cliente que envía JSON o un servicio que responde a su solicitud. Además de verificar los tipos, asegurarse de que sus datos estén como deberían puede eliminar muchos problemas potenciales. Comprender sus límites y lo que tiene y no tiene control es un aspecto importante de la validación.

    La mejor estrategia es validar al margen antes de que su lógica tenga lugar. Cuando un cliente envía algunos datos a su API, aplica la validación antes de hacer cualquier otra cosa con esos datos. Asegúrese de que el correo electrónico sea una dirección de correo electrónico real, que la fecha tenga el formato correcto y que la cadena cumpla con los requisitos de longitud.

    Esta simple verificación agregará seguridad y consistencia a su aplicación. Además, cuando reciba datos de un servicio, como una base de datos o un caché, vuelva a validarlos para asegurarse de que el resultado devuelto satisfaga sus comprobaciones de datos.

    Siempre puede validar manualmente o usar bibliotecas de funciones de utilidad como Lodash o Ramda. Funcionan muy bien para objetos de datos pequeños. Bibliotecas de validación como jueves, Sip, o Zod funcionan aún mejor, ya que contienen validaciones comunes que pueden ahorrarle tiempo y esfuerzo y crear un esquema muy legible. Si necesita algo independiente del idioma, compruébelo esquema JSON.

    Resumen

    La validación no es atractiva, pero puede ahorrar mucho tiempo que, de lo contrario, se dedicaría a solucionar problemas y escribir scripts de migración de datos. No cometa el error de dejar que su cliente le envíe datos limpios; no desea que se filtren datos maliciosos en su lógica empresarial o almacén de datos persistente. Tómese su tiempo y valide sus puntos finales de API y respuestas de servicio. Si bien puede causar cierta frustración por adelantado, es mucho más fácil aflojar los reinos que apretarlos más tarde.

    Prueba

    La prueba es una buena práctica para el desarrollo de software y debe ser un requisito principal no funcional. Definir una estrategia de prueba puede ser un desafío para cualquier proyecto, incluidas las API. Siempre comprenda sus limitaciones y defina su estrategia en consecuencia.

    Las pruebas de integración son una de las formas más efectivas de probar las API. En este esquema, el equipo de desarrollo crea una prueba para cubrir una parte del flujo de la aplicación, de un punto específico a otro. Un gran flujo de pruebas de integración incluye probar el punto de entrada de la API y simular el punto de solicitud del servicio. Al seleccionar estos dos puntos, cubre toda la lógica, desde el comienzo de la solicitud de la API hasta la solicitud del servicio, y el servicio ficticio le brinda una respuesta para devolver la respuesta de la API.

    Mientras usa simulacros, este método le permite concentrarse en el código en la capa lógica y no depender de los servicios de back-end o la lógica de presentación para probar. La falta de dependencias hace que la ejecución de las pruebas sea mucho más confiable, más fácil de automatizar y más fácil de incluir en la canalización de integración continua.

    Una configuración que uso para usos de prueba de integración Cinta, servidor de prueba, Y simulacro de búsqueda. Estas bibliotecas me permiten realizar pruebas aisladas en puntos finales de API desde la solicitud hasta la respuesta, con Fetch-mock capturando la solicitud saliente en la capa de persistencia.

    Resumen

    Si bien todos los tipos de pruebas y verificación de tipos son beneficiosos para las API, las pruebas de integración ofrecen el mayor beneficio en términos de efectividad sobre el tiempo de creación y administración. El uso de herramientas como Fetch-mock puede ofrecer escenarios de burla limpios en el borde del servicio.

    Centrarse en los fundamentos

    Al diseñar y crear su aplicación y API, asegúrese de incluir estos cuatro elementos principales. Estos no son los únicos requisitos no funcionales a considerar; otros incluyen monitoreo de aplicaciones, registro y administración de API. Aun así, la seguridad, la documentación, la validación y las pruebas son puntos focales cruciales para diseñar y construir una API exitosa para cualquier caso de uso.

    Artículos de interés

    Subir