¿Qué es el diseño de API?

El diseño de API incluye decisiones sobre endpoints de API, formatos de solicitud y respuesta, protocolos y la forma en que las API se comunican con otras aplicaciones y consumidores. El diseño de API también desempeña un papel importante en el gobierno de las API.

El gobierno de las API se refiere al amplio conjunto de normas, políticas y prácticas que dirigen la forma en que una organización desarrolla, implementa y utiliza sus API. El diseño eficaz de API produce API que se adhieren a estas políticas predeterminadas, con documentación sólida y actualizada que explica cómo funciona la API. El resultado son API bien diseñadas que tienen una mejor reutilización, escalabilidad, compatibilidad y proporcionan una mejor experiencia de usuario a sus usuarios finales.

Existen muchos casos de uso de API diferentes y numerosos enfoques para el diseño de API, con algunos protocolos, estilos arquitectónicos y lenguajes más adecuados que otros para tareas o casos de uso específicos.

A medida que el uso de las API web ha aumentado, ha llevado al desarrollo y uso de ciertos protocolos, estilos, estándares y lenguajes. Estas estructuras proporcionan a los usuarios un conjunto de parámetros, o especificaciones de API, que definen los tipos de datos aceptados, los comandos, la sintaxis y mucho más. En efecto, estos protocolos de API facilitan el intercambio estandarizado de información.

Los protocolos, estilos arquitectónicos y lenguajes comunes incluyen:

• SOAP (protocolo simple de acceso a objetos)
• Llamada a procedimiento remoto (RPC)
• WebSocket
• REST (transferencia de estado representacional)
• GraphQL

Elegir la estructura correcta para una nueva API es un aspecto importante del proceso de diseño. Estos protocolos, estilos arquitectónicos y lenguajes no son necesariamente mejores o peores entre sí. Son herramientas diferentes para tareas diferentes.

SOAP es una especificación de protocolo de mensajería ligera basada en XML que permite a los endpoints enviar y recibir datos a través de una serie de protocolos de comunicación, entre ellos SMTP (protocolo simple de transferencia de correo) y HTTP (protocolo de transferencia de hipertexto). SOAP es independiente, lo que permite a las API de SOAP compartir información entre aplicaciones o componentes de software que se ejecutan en entornos distintos o están escritos en lenguajes diferentes.

En comparación con otros tipos de API, las API SOAP tienden a desarrollarse de una manera más formalizada y estructurada. Las API SOAP existen desde la década de 1990; es un formato más antiguo y establecido, pero también más lento que arquitecturas más modernas como REST. 

SOAP funciona codificando datos en formato XML y no admite la transferencia de datos en otros formatos. Por otro lado, las API SOAP no requieren necesariamente HTTP para transportar mensajes, lo que les da más flexibilidad para mover datos. SOAP se considera más seguro que otros protocolos, lo que hace que las API SOAP sean apropiadas en sistemas que manejan datos confidenciales.

La llamada a procedimiento remoto (RPC) es un protocolo que proporciona el paradigma de comunicaciones de alto nivel que se utiliza en el sistema operativo. La RPC implementa un sistema lógico de comunicaciones de cliente a servidor diseñado específicamente para el soporte de aplicaciones de red. El protocolo RPC permite a los usuarios trabajar con procedimientos remotos como si los procedimientos fueran locales. Esto los hace adecuados para situaciones que requieren muchas interacciones cliente/servidor e interacción cliente/servidor.

Las API RPC se pueden dividir en XML-RPC, JSON-RPC y gRPC. XML-RPC es una llamada a procedimiento remoto que utiliza un formato XML específico para transferir datos. Son más antiguas incluso que las API SOAP, pero sencillas y ligeras. JSON-RPC es una llamada a procedimiento remoto que utiliza JSON (JavaScript Object Notation) para transferir datos. Debido a que JSON utiliza estructuras de datos universales, se puede utilizar con cualquier lenguaje de programación. 

gRPC es un marco RPC de código abierto y alto rendimiento desarrollado inicialmente por Google. gRPC usa el formato de datos de protocolo de red HTTP/2 y búferes de protocolo y se usa normalmente para conectar servicios en una arquitectura de microservicios.

Las API WebSocket permiten la comunicación bidireccional entre el cliente y el servidor. Este tipo de API no requiere que se establezca una nueva conexión para cada comunicación: una vez que se establece la conexión, permite un intercambio continuo. Esto hace que las API Web Socket sean ideales para la comunicación en tiempo real. 

El chat en directo, el seguimiento de la ubicación en tiempo real y la transmisión de datos son excelentes casos de uso para las API WebSocket. Las API WebSocket también son útiles para la sincronización de datos, que es la práctica de mantener los datos coherentes y actualizados en varios dispositivos o sistemas, ya que pueden actualizarse en tiempo real, sin necesidad de crear una nueva conexión cada vez que se produce un cambio. realizado.

REST es un conjunto de principios de arquitectura de API web. Las API REST, también conocidas como API RESTful, son API que cumplen con ciertas restricciones de la arquitectura de REST. Las API REST utilizan métodos HTTP como GET, PUT, HEAD y DELETE para interactuar con los recursos. REST hace que los datos estén disponibles como recursos, y cada recurso está representado por un URI único. Los clientes solicitan un recurso proporcionando su URI. Las API REST no tienen estado, es decir, no guardan los datos del cliente entre solicitudes.

Las API RESTful son populares porque son ligeras, flexibles y fáciles de usar. Son totalmente compatibles con el transporte de mensajes en diferentes formatos (como texto sin formato, HTML, YAML, XML y JSON), y también admiten el almacenamiento en caché. Si bien esto los hace útiles en una gran variedad de contextos, algunas estaciones requieren un lenguaje o protocolo más específico para completar una tarea de manera eficiente.

GraphQL es un lenguaje de consulta y tiempo de ejecución de API que Meta desarrolló internamente en 2012 antes de convertirse en código abierto en 2015. GraphQL permite a los usuarios realizar solicitudes de API con solo unas pocas líneas, en lugar de tener que acceder a endpoints complejos con muchos parámetros. Esta capacidad puede facilitar la generación y respuesta a las consultas de API, en particular las solicitudes más complejas o específicas que se dirigen a varios recursos.

Dado que Meta desarrolló este lenguaje de consulta para hacer que sus aplicaciones móviles fueran más eficientes, tiene sentido que las API GraphQL sean útiles para aplicaciones móviles. Al ofrecer un único punto de entrada, las API GraphQL pueden reducir los tiempos de carga consultando datos sin tener que realizar varias solicitudes al servidor. 

Hay cuatro etapas clave en el proceso de diseño de una API:

• Plan
• Desarrollo
• Prueba
• Despliegue

Todos estos pasos requieren la colaboración entre las principales partes interesadas de la API. Aunque algunos de los pasos son más adecuados para algunas partes interesadas que para otras, el diseño de la API debe seguir siendo colaborativo durante todo el proceso. Esto ayuda a los desarrolladores a evitar añadir funciones adicionales que el programa no necesita, acelerando el proceso de desarrollo en general.

El primer paso de cualquier proyecto es hacer que todos participen en el tipo de nueva API que están creando. Una API pública destinada a que los clientes interactúen con ella en un entorno de comercio electrónico tiene necesidades de diseño y funciones diferentes a las de una API destinada a utilizarse internamente para un flujo de trabajo de autenticación; es importante que todas las partes interesadas comprendan los casos de uso de una posible API antes de que comience el desarrollo.

Comprender qué es lo que está creando una empresa (y por qué) puede dar a los desarrolladores una mejor idea de cómo crearlo, incluidos los protocolos a utilizar. Si, por ejemplo, esta API potencial requiere comunicación en tiempo real, los desarrolladores saben que podrían usar WebSocket al crearla porque ese protocolo se adapta bien a ese propósito. 

Una vez que las partes interesadas tengan una visión clara de lo que será la API y cómo funciona, es hora de empezar a crearla. Durante el proceso de desarrollo de API, los desarrolladores definen los endpoints; diseñan el modelo de datos para la API; se aseguran de que la API se adhiere a las políticas de seguridad API y devuelve códigos de estado estándar para los errores; si es necesario, implementan mecanismos de autenticación como encabezados HTTP, claves API, OAuth o JSON Web Tokens (JWT); definen códigos de error, mensajes y respuestas.

Otra parte del proceso de desarrollo es la documentación. Mientras se crea la API, todas las opciones que se toman deben capturarse en un documento legible por humanos y por máquinas. Un documento legible por humanos está escrito en un lenguaje natural y fácil de entender. Un documento legible por máquina debe adherirse a una especificación API, como la especificación OpenAPI, que estandariza el formato para que sea coherente y pueda integrarse en sistemas futuros.

El diseño de API puede ser un proceso altamente iterativo; especialmente si las API exponen datos confidenciales, es importante probarlas rigurosamente para detectar errores y fallas. Después de crear algo, es importante ver si funciona según lo previsto. Una parte importante de las pruebas de las API es la simulación, que es el proceso de crear servidores simulados con datos de muestra para comprobar si la API se comunica correctamente con sus endpoint y devuelve los resultados esperados. 

La simulación se puede realizar junto con las pruebas de API. Las pruebas de API incluyen pruebas de contrato, que establecen cómo deben ser una solicitud y una respuesta; pruebas unitarias, que confirman que un único endpoint ofrece la respuesta esperada; pruebas de carga, que comprueban si la API es capaz de funcionar en condiciones de tráfico máximo y pruebas de principio a fin, que validan los recorridos de los usuarios que implican comunicarse con más de una API. Las pruebas se pueden realizar manualmente o mediante la implementación de marcos de pruebas automatizados.

Si todo funciona según lo previsto, la API está lista para su lanzamiento y se puede implementar. En este momento, es importante que la documentación de la API esté finalizada para que otros usuarios y sus máquinas puedan integrar correctamente esta API en su entorno de red informática. Es posible que una vez lanzada la API, los usuarios encuentren problemas que las partes interesadas no previeron. Es útil contar con una estrategia de control de versiones antes del lanzamiento de la API, de modo que si los desarrolladores necesitan actualizar la aplicación, lo hagan de forma clara y coherente.

Un enfoque basado en API para el desarrollo de aplicaciones prioriza el diseño de API al principio del proceso de desarrollo de software y crea aplicaciones con servicios que se entregarán a través de API. La idea es que, al priorizar el diseño de API desde el principio en el desarrollo de software, las API resultantes sean más reutilizables, seguras, eficientes, fáciles de usar y estén mejor alineadas con los objetivos de la organización. Este enfoque se opone a un enfoque basado en código, que pone la lógica de este en primer lugar, y los desarrolladores crean API para que encajen en el software más tarde. 

El diseño de API es clave en los enfoques basados en API. En ellos, las API son fundamentales para el desarrollo de aplicaciones y un diseño bien considerado promueve el desarrollo de aplicaciones más valiosas y con mejor rendimiento. 

Las sólidas prácticas de diseño de API también pueden ayudar a mejorar tanto la experiencia del desarrollador como la experiencia del usuario final al descubrir y resolver los inconvenientes de desarrollo y rendimiento antes de que se conviertan en problemas mayores.

Las partes interesadas pueden establecer desde el principio del proceso de desarrollo que todas las aplicaciones de la empresa se integran y funcionan bien entre sí. Cuando se implementa con éxito, un enfoque basado en API con una documentación completa permite a los desarrolladores reutilizar las API existentes en lugar de volver a crear funciones que ya existen.

Las API REST (o RESTful) tienen una estructura flexible. El único requisito es que se alineen con los siguientes seis principios de diseño REST, también conocidos como restricciones arquitectónicas: interfaz uniforme, desacoplamiento cliente/servidor, ausencia de estado, capacidad de almacenamiento en caché, arquitectura de sistema en capas y, opcionalmente, código bajo demanda. 

Estas restricciones arquitectónicas hacen que las API RESTful se adapten bien a un enfoque basado en API: el desacoplamiento cliente/servidor y la ausencia de estado son especialmente útiles. 

En una API RESTful, las aplicaciones cliente y servidor deben ser independientes entre sí. La única información que la aplicación cliente debe conocer es el identificador uniforme de recursos (URI) del recurso solicitado; no puede interactuar con la aplicación del servidor de ninguna otra manera. 

Las API RESTful también son sin estado, lo que significa que cada solicitud debe incluir toda la información necesaria para procesarla. En otras palabras, las API REST no requieren ninguna sesión del lado del servidor. Estas restricciones hacen que estas API sean independientes de los servidores de una empresa, lo que las hace flexibles: las aplicaciones del lado del cliente y del servidor se pueden escribir con diferentes lenguajes y protocolos sin afectar el diseño de la API.

Las API RESTful también son una buena opción para un entorno basado en API, ya que son escalables y ligeras. La separación entre el cliente y el servidor mejora la escalabilidad porque las API RESTful no necesitan retener información de solicitudes anteriores del cliente, lo que reduce los cuellos de botella en la comunicación. El almacenamiento en caché eficaz también puede reducir las interacciones cliente/servidor, otra ventaja para la escalabilidad. Dado que las API RESTful utilizan el formato HTTP para el transporte de mensajes, pueden aceptar la transferencia de datos en varios formatos. Esto puede simplificar la integración en nuevos entornos.

Una arquitectura de microservicios es un estilo arquitectónico nativo de la nube en el que una sola aplicación se compone de muchos componentes o servicios más pequeños acoplados de forma flexible e implementables de forma independiente. Las API REST se utilizan a menudo para permitir la comunicación entre estos servicios más pequeños.

Un enfoque basado en API encaja bien con el esquema de arquitectura de microservicios porque las API se utilizan para conectar los servicios entre sí. Si el diseño de API se convierte en una prioridad dentro de una organización y las API están diseñadas para comunicarse de manera fluida entre sí, los desarrolladores ahorran tiempo al empaquetar esos servicios en aplicaciones más grandes. 

Para obtener el máximo valor de las API empresariales, las organizaciones suelen hacer hincapié en:

• Gobierno y documentación de API
• Recopilación de feedback de las partes interesadas
• Autenticación adecuada
• Versiones
• Estandarización de mensajes de error
• Escalado y contexto
• Coherencia

Estos principios ayudan a mantener informadas a todas las partes interesadas durante todo el proceso de diseño de API y a garantizar que las API se alineen con los objetivos y la estrategia de la organización.  

Gobierno y documentación de API: establecer una estrategia de gobierno y documentación de API en toda la organización desde el principio ayuda a promover la coherencia y facilita la navegación por el portfolio de API de una empresa. Por ejemplo, una organización podría decidir adoptar una especificación como OpenAPI para que todas las API empresariales se adhieran a un estándar del sector. En cualquier caso, mantener un gobierno y una documentación adecuados y coherentes permite a los nuevos usuarios de la API comprender rápidamente la API y sus funciones. 

Recopilación de feedback de las partes interesadas: las aportaciones iniciales de las principales partes interesadas y los consumidores de API ayudan a mantener a los desarrolladores en el camino correcto durante todo el proceso de desarrollo. Una mala comunicación puede provocar retrasos en el desarrollo de API y reducir su valor.

Autorización adecuada y seguridad de API: para proteger las API, así como los datos confidenciales, las organizaciones implementan técnicas de autorización que proporcionan validación para las solicitudes de API. Los mecanismos de autenticación, como las claves de API, OAuth y JSON Web Tokens (JWT), proporcionan diferentes métodos para proteger los datos y el tráfico de API. El cifrado de API, el proceso de codificación de datos para viajar entre el cliente y el servidor, también se utiliza para proteger los datos y las API.

Pruebas y control de versiones: las pruebas de API incluyen cubrir varios escenarios, positivos y negativos, para identificar problemas antes de implementar una API. Las API evolucionan a lo largo de estas pruebas y los desarrolladores crean nuevas versiones que corrigen errores o mejoran el rendimiento. Las nuevas versiones de la API también se publican por otros motivos, como cuando los desarrolladores añaden nuevas características a una API. El control de versiones es la forma en que los desarrolladores gestionan los cambios en una API, hacen que los cambios sean transparentes y se aseguran de que las actualizaciones no interrumpan a los usuarios actuales.

Es útil tener mecanismos de control de versiones (como el control de versiones basado en URL o el control de versiones basado en encabezados) definidos antes de que el desarrollo comience en serio. 

Estandarización de los mensajes de error: una gestión adecuada de los errores mejora la experiencia de un consumidor de API porque ayuda a solucionar problemas cuando las cosas van mal. Los códigos de error, los mensajes y las respuestas deben describir con precisión la naturaleza del error y seguir siendo claros y coherentes.

Contexto y restricciones: cada API existe en un contexto específico que determina cómo se creará y cuáles son sus funciones. Los plazos de los proyectos, los volúmenes de tráfico esperados y si la empresa prioriza la API o el código pueden dar forma a la API resultante. Es importante que todas las partes interesadas conozcan esta información para que puedan tomar decisiones informadas durante el proceso de desarrollo.

Coherencia: por encima de todo, mantener la coherencia en todos los aspectos suele conducir a un mejor diseño de API. La coherencia en el diseño de API es algo más que el control de versiones y los códigos de error. Al definir endpoints, mantener la coherencia de las convenciones de nomenclatura puede facilitar su identificación. Al realizar una solicitud específica a una API, debe resolverse de la misma manera cada vez. Cuando todo es coherente en un panorama de API, también es más fácil documentar las API para que sean comprensibles para los futuros usuarios.