¿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 la gobernanza de API.

La gobernanza de API se refiere al conjunto integral de estándares, políticas y prácticas que dirigen la forma en que una organización desarrolla, despliega y emplea 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 mejor reutilización, escalabilidad y compatibilidad, y brindan una mejor experiencia para 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 para tareas o casos de uso específicos que otros.

A medida que ha aumentado el uso de API web, 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 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 variedad de protocolos de comunicación, incluidos SMTP (protocolo simple de transferencia de correo) y HTTP (protocolo de transferencia de hipertexto). SOAP es independiente, lo que permite que las API de SOAP compartan información entre aplicaciones o componentes de software que se ejecutan en diferentes entornos o están escritos en diferentes lenguajes.

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 las 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 necesariamente requieren 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 de 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. RPC implementa un sistema lógico de comunicaciones de cliente a servidor que está diseñado específicamente para el soporte de aplicaciones de red. El protocolo RPC permite a los usuarios trabajar con procedimientos remotos como si fueran locales. Esto los hace adecuados para situaciones que requieren muchas interacciones cliente/servidor e interacción cliente/servidor.

Las API de 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 de SOAP, pero son 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 usar con cualquier lenguaje de programación. 

gRPC es un marco de infraestructura de código abierto y alto rendimiento desarrollado inicialmente por Google. gRPC utiliza el protocolo de red HTTP/2 y el formato de datos Protocol Buffers y se usa comúnmente para conectar servicios en una arquitectura de microservicios.

Las API de 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 de Web Socket sean ideales para la comunicación en tiempo real. 

El chat en vivo, el seguimiento de ubicación en tiempo real y la transmisión de datos son excelentes casos de uso para las API de WebSocket. Las API de 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. hecho.

REST es un conjunto de principios de arquitectura de API web. Las API REST también conocidas como API RESTful) son API que se adhieren a ciertas restricciones arquitectónicas REST. Las API REST utilizan métodos HTTP como GET, PUT, HEAD y DELETE para interactuar con los recursos. REST pone los datos a disposición como recursos, con cada recurso representado por un URI único. Los clientes solicitan un recurso proporcionando su URI. Las API REST no tienen estado: no guardan los datos del cliente entre solicitudes.

Las API RESTful son populares porque son ligeras, flexibles y fáciles de usar. Admiten plenamente 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 consultas de API, en particular solicitudes más complejas o específicas dirigidas a múltiples recursos.

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

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

• Plan
• Desarrolle
• Pruebe
• Implemente

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

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

Comprender lo que una empresa está construyendo (y por qué) puede dar a los desarrolladores una mejor idea de cómo construirlo, incluyendo qué protocolos usar. 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 es muy adecuado para ese propósito. 

Una vez que los stakeholders tienen una visión clara de lo que será la API y cómo funciona, es hora de comenzar a construirla. Durante el proceso de desarrollo de API, los desarrolladores definen el endpoint de las API; diseñan el modelo de datos para la API; se aseguran de que la API cumple con las políticas de seguridad de API y devuelva códigos de estado estándar para errores; si es necesario, implementar mecanismos de autenticación como cabeceras 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 cumplir con una especificación de 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 en busca de 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 creación de servidores simulados con datos de muestra para comprobar si la API se comunica correctamente con sus endpoints 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 puede funcionar en condiciones de tráfico pico y pruebas de extremo a extremo, que validan los recorridos del usuario que implican comunicarse con más de una API. Las pruebas se pueden realizar manualmente o mediante la implementación de infraestructura de pruebas automatizadas.

Si todo funciona según lo previsto, la API está lista para su lanzamiento y despliegue. 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 que se lanza la API, los usuarios encuentren problemas con ella que los stakeholders no anticiparon. Es útil contar con una estrategia de control de versiones antes del lanzamiento de la API para que, si los desarrolladores necesitan actualizar la aplicación, lo hagan de manera clara y coherente.

Un enfoque API-first para el desarrollo de aplicaciones prioriza el diseño de API al comienzo 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 y fáciles de usar, y que estén mejor alineadas con los objetivos de la organización. Este enfoque se opone al enfoque de código primero, que pone la lógica del código en primer lugar, y los desarrolladores crean API para que se ajusten al software más adelante. 

El diseño de API es clave en un enfoque API-first. En API-first, las API son fundamentales para el desarrollo de aplicaciones y un diseño bien considerado promueve el desarrollo de aplicaciones más valiosas y de mejor rendimiento. 

Las prácticas sólidas 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 problemas de desarrollo y rendimiento antes de que se conviertan en problemas mayores.

Los stakeholders 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 API-first con 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, sin estado, capacidad de caché, arquitectura del sistema en capas y, opcionalmente, código bajo demanda. 

Estas restricciones arquitectónicas hacen que las API RESTful se adapten bien a un enfoque API-first: el desacoplamiento cliente/servidor y sin estado son útiles en particular. 

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 tampoco tienen 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 API-first porque 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. Debido a que las API RESTful utilizan el formato HTTP para el transporte de mensajes, pueden aceptar la transferencia de datos en múltiples 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 poco acoplados y desplegables de forma independiente. Las API REST se utilizan a menudo para permitir la comunicación entre estos servicios más pequeños.

Un enfoque API-first 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 perfectamente 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:

• Gobernanza y documentación de API
• Recopilación de feedback de stakeholders
• Autenticación adecuada
• Mantenimiento de versiones
• Estandarización de mensajes de error
• Escalado y contexto
• Coherencia

Estos principios ayudan a mantener informados a todos los stakeholders 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.  

Gobernanza y documentación de API: establecer una estrategia de gobernanza y documentación de API en toda la organización desde el principio ayuda a promover la coherencia y facilita la navegación por la cartera de API de una empresa. Por ejemplo, una organización podría optar por adoptar una especificación como OpenAPI para que todas las API empresariales se adhieran a un estándar de toda la industria. En cualquier caso, mantener una gobernanza y una documentación adecuadas y coherentes permite a los nuevos usuarios de API obtener una comprensión rápida de la API y sus funciones. 

Recopilación de feedback de los stakeholders: la entrada temprana de los principales stakeholders y los consumidores de API ayuda 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 API menos valiosas.

Autenticación adecuada y seguridad de API: para proteger las API, así como los datos confidenciales, las organizaciones implementan técnicas de autenticació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 desplegar una API. Las API evolucionan a lo largo de estas pruebas y los desarrolladores crean nuevas versiones que arreglan errores o mejoran el rendimiento. Las nuevas versiones de API también se lanzan por otras razones, como cuando los desarrolladores agregan 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. 

Estandarizar los mensajes de error: el manejo adecuado de 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 construirá y cuáles son sus funciones. Los plazos de los proyectos en competencia, 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 todos los stakeholders conozcan esta información para que puedan tomar decisiones informadas durante el proceso de desarrollo.

Coherencia: por encima de todo, mantener la coherencia generalmente conduce a un mejor diseño de API. La coherencia en el diseño de API es más que solo versiones y 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 escenario de API, también es más fácil documentar las API para que sean comprensibles para los usuarios futuros.