Una API es una interfaz de programación para la comunicación entre aplicaciones o componentes. Las API se dividen en privadas y públicas. Las API privadas se utilizan dentro de una empresa si, por ejemplo, tiene varios productos de software que se comunican entre sí. Los desarrolladores externos pueden utilizar las API públicas. Es cierto que en algunos casos hay que pagarlo. Pero entonces los requisitos del usuario para la calidad y usabilidad de la API también serán mayores.
Cuando los servicios de API se hacen públicos, no ocurre ningún milagro. El número de usuarios no crece y, en general, puede olvidarse de hacer que esta funcionalidad sea de pago (excluimos los casos en los que el producto se promociona debido a que el marketing se basa en publicidad agresiva).
Y si los ingresos de la empresa dependen directamente de la API pública, entonces hay mucho en juego. Esta idea se analiza con más detalle en el libro “API Continuous Development. Las decisiones correctas en un panorama tecnológico cambiante ”(Mehdi Medjui, Ronnie Mitra, etc.):
e iremos más allá ... Los
desarrolladores pueden centrarse principalmente en implementar todas las funciones planificadas en la API. Pero hay requisitos "no funcionales" que a menudo no se cumplen por completo y requieren una atención especial.
En mi opinión, para todas las API es imperativo que los siguientes requisitos no funcionales se cumplan con buena calidad:
- Seguridad
- Documentación
- Validación
- Pruebas
Seguridad
Probablemente no valga la pena explicar por qué la seguridad fue lo primero. He identificado cuatro de los desafíos de seguridad más importantes:
- Usar HTTPS con certificados SSL
- Compartir recursos de diferentes fuentes (CORS)
- Autenticación y tokens web JSON
- Privilegios de autorización y acceso
* De ahora en adelante, limitaremos el contexto a REST y JSON API.
1. Uso de HTTPS con certificados SSL
HTTPS que utiliza certificados SSL es ahora el estándar de seguridad de facto. Para generar certificados, yo personalmente uso Let's Encrypt , una CA automatizada y gratuita de la organización sin fines de lucro Internet Security Research Group (ISRG).
Estos certificados aseguran que los datos que van de su API al usuario estén encriptados.
2. Compartir recursos de diferentes fuentes (CORS)
Para mantener seguras las solicitudes a otras fuentes, los navegadores utilizan un mecanismo llamado CORS. CORS son las siglas de Cross-Origin Resource Sharing, una tecnología para compartir recursos de diferentes fuentes. Aunque los navegadores (en virtud de la misma regla de fuente) no permiten el acceso a recursos de diferentes fuentes, CORS le permite eludir estas restricciones y al mismo tiempo garantizar que el acceso a los recursos sea seguro.
Los agentes de usuario (por ejemplo, navegadores), basados en los valores de los encabezados adicionales para CORS en la solicitud HTTP, pueden realizar solicitudes a otras fuentes que se bloquearían sin CORS.
Aquí hay un ejemplo : una
página HTML servida por un servidor de http://domain-a.com solicita src en http://domain-b.com/image.jpg .
Muchas páginas cargan recursos como estilos CSS, imágenes y scripts de diferentes dominios correspondientes a diferentes CDN (redes de entrega de contenido). La
implementación de CORS para Node.js es bastante popular hoy en día .
3. Autenticación y tokens web JSON (JWT)
Hay varios enfoques para la autenticación de usuarios de API, pero uno de los mejores es el uso de JWT. Estos tokens se firman mediante varios algoritmos criptográficos.
JSON Web Token es un estándar abierto para crear tokens de acceso basados en el formato JSON. Normalmente se utiliza para pasar datos de autenticación en aplicaciones cliente-servidor.
Para crear un token, debe definir un encabezado con información general sobre el token, la carga útil, como la identificación de usuario, el rol, etc., así como las firmas. En términos simples, JWT es solo una cadena con el siguiente formato header.payload.signature.
Cuando el cliente inicia sesión, el servicio de administración de identidad proporciona el JWT al cliente. Luego, el cliente puede usar este token para realizar solicitudes de API. La API tiene acceso a una clave pública o un secreto que utiliza para validar el token.
Para la verificación, puede utilizar, por ejemplo, la biblioteca jsonwebtoken . A continuación se muestra el código JavaScript:
import jwt from 'jsonwebtoken'
export default function (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken (req)
jwt.verify (token, SECRET, {algoritmos: ['HS256']}, (err, decodificado) => {
the if (err) {next (err)}
req.session = Decoded
next ()
})
}
Más información sobre JWT, bibliotecas y lenguajes de programación compatibles - JWT.io en línea .
4. Autorización y privilegios de acceso
La autenticación es importante, pero la autorización es igual de importante: ¿un cliente que se autenticó y recibió el JWT tiene el privilegio de ejecutar una solicitud en particular?
Para probar esto, usamos un alcance. Al analizarlo, el servicio de API determina si esta solicitud de cliente se puede cumplir sin costosas búsquedas de ACL.
El alcance es un bloque de texto (generalmente separado por espacios) que describe los privilegios de acceso de un punto final de API. Describe los recursos y acciones que se les pueden aplicar. Esta formalización funciona bien para las API REST / JSON, ya que tienen una estructura muy similar.
RECURSO: ACCIÓN (por ejemplo, ARTÍCULO: ESCRIBIR o ARTÍCULO: LEER, donde ARTÍCULO es un recurso y LEER y ESCRIBIR son acciones).
Esto permite a los desarrolladores de API centrarse en funciones en lugar de roles o usuarios. El servicio de gestión de identidades puede asociar roles y usuarios con ámbitos específicos y luego, junto con el JWT, enviar el ámbito al cliente.
Dormir tranquilamente
Al desarrollar e implementar API, la seguridad siempre debe ser uno de los requisitos más importantes. Por supuesto, puede hablar y escribir sobre él sin cesar, pero la implementación competente de las cuatro tareas descritas en producción ya le permitirá dormir bien.
Documentación
¿Qué podría ser peor que la falta de documentación? ¡Documentación desactualizada!
Los desarrolladores son ambiguos sobre la documentación. Muchos claramente no tienen mucho amor por este negocio. Sea como fuere, esta tarea es muy importante, especialmente cuando se trata de la API pública. Los desarrolladores externos deberían poder aprender a usarlo. Además, una buena documentación lo ayudará a capacitar a nuevos desarrolladores que se unan a su equipo más rápido.
La documentación de la API debe incluir tres secciones básicas:
- Introducción (README)
- Hoja de datos (especificaciones)
- Ejemplos de uso (Introducción y otras subsecciones similares)
1. LÉAME
La documentación debe informarle sobre para qué sirve la API, cómo configurar el entorno, cómo probar el servicio, cómo implementar el proyecto. Por supuesto, los usuarios también necesitan saber cómo y dónde informar dificultades o problemas.
Esto está escrito en el archivo README. Este archivo generalmente también se coloca en el repositorio, brinda a los desarrolladores un punto de partida para trabajar con su proyecto.
El archivo README debe contener:
- Descripción API
- Enlaces a referencias técnicas y manuales
- Guía de configuración para desarrolladores
- Guía del probador
- Guía de implementación
- Gestión de la dependencia
- Guía del colaborador
- Código de conducta
- Licencia
- Gracias
Sea conciso en su archivo README; no es necesario que explique todos los matices, pero proporcione suficiente información para que los desarrolladores se sumerjan en su proyecto.
2. Especificaciones
En la API REST / JSON, cada punto final es una función creada para un propósito específico. Es importante tener documentación técnica que describa cada punto final, entradas y salidas, y cómo funciona el servicio con diferentes clientes.
Puede crear su propia documentación de API basada en OpenAPI .
Es una especificación y un marco completo para describir, crear, consumir y renderizar servicios web REST. Su trabajo es permitir que los sistemas de documentación sincronicen sus actualizaciones con los cambios en el servidor. Los métodos, parámetros, modelos y otros elementos se integran con el software del servidor a través de OpenAPI y se sincronizan con él todo el tiempo.
3. Ejemplos de uso
Es poco probable que los usuarios de la API estén contentos si simplemente les vuelves las especificaciones. Quieren saber cómo usar su API en situaciones específicas y cómo resolver problemas comunes. La mayoría de los usuarios potenciales tienen problemas y recurren a su API para resolverlos.
Una excelente manera de presentar a los usuarios su API es crear una subsección de Introducción. Esto lo ayudará a comprender los casos de uso típicos y utilizarlos para evaluar los beneficios de su API.
Tres ballenas
La documentación es un componente clave de cualquier API. Al redactar la documentación, tenga en cuenta los tres pilares de la documentación de API exitosa: archivos README, especificaciones y casos de uso. ¡Y usted (y sus usuarios) estarán felices!
Validación de datos
Un aspecto importante del desarrollo de API, la validación de datos, a menudo es pasado por alto por muchos. La validación es el proceso de validar la entrada de fuentes externas. Estas fuentes pueden ser un cliente que envía JSON o un servicio que responde a su solicitud. Esta verificación asegurará que los datos sean exactamente como deberían ser. Gracias a él, puede eliminar muchos problemas potenciales. Una tarea importante de la validación es comprender qué formato y qué rango de valores deben tener los datos de entrada y cómo controlarlos.
La mejor estrategia es ejecutar la validación antes de que su servicio realice cualquier manipulación de datos. Cuando un cliente envía sus datos a su API, como correo electrónico, fecha y nombre, asegúrese de que en realidad sea una dirección de correo electrónico, que la fecha tenga el formato correcto y que la cadena cumpla con los requisitos de longitud. Esta simple verificación hará que su servicio sea más seguro y organizado.
Además, cuando obtenga datos de un servicio, de algún tipo de base de datos o caché, vuelva a verificarlo para asegurarse de que el resultado devuelto sea el esperado.
Puede implementar la validación a mano, pero también se pueden utilizar bibliotecas como Lodash o Ramda para este propósito .... Son ideales para pequeños objetos de datos. Las bibliotecas como Joi , Yup o Zod funcionan incluso mejor porque le permiten describir un marco de validación general, lo que le ahorra tiempo y esfuerzo. Si necesita algo independiente de un lenguaje de programación en particular, eche un vistazo a JSON Schema .
Mejor mantenlo afuera
La validación no es nada emocionante, pero puede ahorrarle mucho tiempo que, de otro modo, dedicaría a solucionar problemas y escribir scripts de migración de datos. No cometa el error de confiar en que su cliente le enviará datos no verificados si no desea que los datos incorrectos terminen en la lógica o el almacenamiento de su negocio.
Tómese su tiempo y organice la validación de su entrada. Como dice el refrán, es mejor exagerar que perderlo.
Pruebas
Las pruebas son una parte integral del ciclo de vida del software. En nuestro caso, debería percibirse como uno de los requisitos no funcionales clave. Definir una estrategia de prueba puede ser una tarea abrumadora para cualquier proyecto, incluida una API de servicio. Siempre trate de ser consciente de sus limitaciones y defina su estrategia en consecuencia.
Las pruebas de integración son uno de los métodos de prueba de API más eficaces. Su tarea es verificar que la aplicación pase correctamente de un estado a otro. En nuestro caso, el conjunto de pruebas de integración debe incluir probar los puntos de entrada de la API del servicio, así como maquetas para simular el envío de una solicitud y recibir una respuesta. Así es como comprobamos el caso de prueba principal de nuestro servicio.
Este método le permite enfocarse solo en la lógica de procesamiento de datos, sin considerar los internos de los servicios de backend o la lógica de presentación de datos. La falta de dependencias hace que la ejecución de la prueba sea más confiable, más fácil de automatizar y más fácil de incorporar en una canalización de integración continua.
Para las pruebas de integración, utilizo Tape , Test-server y Fetch-mock . Estas bibliotecas le permiten ejecutar pruebas aisladas en puntos finales de API, desde la solicitud hasta la respuesta.
Juego de imitación
Otros tipos de pruebas y verificación de tipos también son ciertamente útiles, y las pruebas de integración tienen la mayor ventaja: es altamente eficiente con menos horas de trabajo dedicadas a escribir y mantener pruebas. Y el uso de herramientas como Fetch-mock puede proporcionar una simulación completa del intercambio de datos.
No te detengas ahí
Una vez que haya completado los cuatro requisitos no funcionales, no se detenga allí. Hay algunos más: monitoreo de aplicaciones, registro y administración de API. Pero en cualquier caso, la seguridad, la documentación, la validación y las pruebas deben ser lo primero.
Los servidores en la nube de Macleod son rápidos y seguros.
Regístrese usando el enlace de arriba o haciendo clic en el banner y obtenga un 10% de descuento durante el primer mes de alquiler de un servidor de cualquier configuración.
