API


Concepto general

Una API (Application Programming Interface) define un conjunto de reglas que permiten la comunicación entre diferentes sistemas, aplicaciones o servicios. Es una capa de abstracción que facilita la interoperabilidad y desacopla los componentes.
Su diseño adecuado influye directamente en la escalabilidad, seguridad, rendimiento y mantenibilidad del sistema.


Tipos principales de APIs

  • APIs locales: entre módulos o librerías dentro del mismo proceso o aplicación.
  • APIs remotas: comunicación entre sistemas a través de red, generalmente sobre HTTP o gRPC.
  • APIs abiertas (Open API / Public APIs): expuestas públicamente para que otros desarrolladores las utilicen.
  • APIs privadas: usadas internamente dentro de una organización.
  • APIs de partners: restringidas a socios o clientes específicos, con control de acceso.

Estilos y tecnologías

REST

  • Basado en el protocolo HTTP y el concepto de transferencia de estado representacional.
  • Cada recurso tiene un URI único y se accede mediante verbos HTTP (GET, POST, PUT, DELETE, PATCH).
  • Se apoya en formatos ligeros como JSON.
  • Escalable y fácil de cachear.

Buenas prácticas

  • Versionar rutas (/api/v1/...)
  • Usar respuestas consistentes con códigos HTTP adecuados.
  • Incluir paginación, filtros y ordenamiento.
  • Evitar sobrecargar endpoints.

SOAP

  • Basado en XML y mensajería estructurada mediante el protocolo HTTP o SMTP.
  • Enfocado en transacciones seguras y complejas (banca, seguros, etc.).
  • Requiere un WSDL (Web Services Description Language) para describir los métodos disponibles.
  • Más estricto y pesado que REST, pero más formal y estandarizado.

GraphQL

  • Define un lenguaje de consultas que permite al cliente especificar exactamente qué datos necesita.
  • Optimiza las llamadas, evitando overfetching y underfetching.
  • Ideal para frontends modernos (React, Vue, etc.) y microservicios.
  • Requiere un schema fuertemente tipado y un resolutor por cada campo o tipo.

FastApi

  • Framework de Python moderno y asíncrono para construir APIs REST o híbridas.
  • Integración nativa con OpenAPI y swagger para documentación automática.
  • Soporta validación mediante Pydantic y es altamente eficiente gracias a Starlette.

Documentación

OpenAPI y swagger

  • Permiten describir, probar y documentar APIs REST de forma estandarizada.
  • Swagger UI genera interfaces visuales para interactuar con los endpoints.
  • OpenAPI define un formato JSON/YAML que describe rutas, modelos y respuestas.

Ejemplo básico de definición OpenAPI (YAML):

openapi: 3.0.0
info:
	title: Sample API
	version: 1.0.0
paths:
	/users:
		get:
			summary: Get all users
			responses:
				'200':
					description: List of users

`


Pruebas de APIs

JMeter

  • Herramienta para pruebas de rendimiento, carga y estrés en servicios web.
  • Permite crear escenarios concurrentes y analizar métricas de latencia, throughput y errores.

Clientes y testing local

axios

  • Cliente HTTP basado en Promesas para JavaScript.
  • Facilita las peticiones AJAX o RESTful desde frontend o Node.js.
  • Soporta interceptores, cancelación de peticiones y configuración global de cabeceras.

Ejemplo básico:

axios.get('/api/users')
	.then(response => console.log(response.data))
	.catch(error => console.error(error));

fetch

  • API nativa de JavaScript para realizar solicitudes HTTP.
  • Basada en Promesas, más moderna que XMLHttpRequest.

Ejemplo básico:

fetch('/api/users')
	.then(res => res.json())
	.then(data => console.log(data))
	.catch(err => console.error(err));

ngrok

  • Túnel seguro que expone servicios locales a Internet mediante una URL pública.
  • Ideal para probar webhooks o APIs en desarrollo sin desplegarlas.

APIs y microservicios

  • Cada microservicio suele exponer su propia API independiente.
  • Comunicación entre ellos mediante REST, GraphQL, gRPC o colas de mensajes (RabbitMQ, Kafka).
  • Es común usar API Gateways para unificar rutas, aplicar políticas de seguridad y manejar versiones.

web services

  • Término general para describir servicios accesibles vía red.
  • Incluye tanto REST como SOAP.
  • Pueden implementarse en arquitecturas monolíticas, distribuidas o basadas en microservicios.

Consideraciones finales

  • Aplicar seguridad con OAuth2, JWT o API Keys.
  • Implementar rate limiting y monitorización.
  • Usar versionado y documentación viva para mantener compatibilidad.
  • Adoptar prácticas de observabilidad: logs estructurados, métricas y trazas distribuidas.

API Nuevos Conceptos y Temas Complementarios

Escalabilidad, rendimiento y estado

  • Estado y “stateless”
    • Un sistema que sigue los principios de Representational State Transfer (REST) debe ser stateless: cada petición del cliente al servidor debe contener toda la información necesaria para procesarla. :contentReference[oaicite:2]{index=2}
    • Esto permite mejor escalabilidad horizontal, ya que cualquier nodo puede responder sin dependencias del estado de otros nodos.
  • Cacheado y rendimiento
    • En REST se puede aprovechar el caché HTTP (ETags, Cache-Control) para reducir la carga del servidor.
    • En arquitecturas de microservicios opcionales, se deben considerar también colas, mensajería asíncrona o WebSockets para mejorar la tolerancia a fallos.

Modelo de madurez de las APIs

  • Richardson Maturity Model (RMM) evalúa qué tan “RESTful” es una API según niveles de adopción de recursos, verbos HTTP, hipermedia. :contentReference[oaicite:4]{index=4}
    • Nivel 0: todo pasa por un único endpoint (como RPC).
    • Nivel 1: recursos con URIs distintas.
    • Nivel 2: uso de verbos HTTP correctos.
    • Nivel 3: hipermedia (HATEOAS) — enlaces dinámicos en las respuestas.
  • Este modelo ayuda a diseñar y valorar APIs más maduras y flexibles.

Gestión y ciclo de vida de APIs

  • API management engloba la administración del ciclo de vida de una API: diseño, publicación, versiones, seguridad, analítica. :contentReference[oaicite:6]{index=6}
  • Componentes clave:
    • Puerta de enlace de API (API Gateway) para autenticar, limitar peticiones, enrutar.
    • Portal de desarrolladores y comunidad para que terceros descubran, prueben y usen tus APIs.
    • Versionado de API: mantener compatibilidad retroactiva mientras avanzas con nuevas versiones (/v1, /v2, etc.).
    • Métricas de uso: latencia, tasa de errores, volumen de datos, usuarios activos.

Seguridad, autenticación y autorización

  • Autenticación: Verificar identidad (por ejemplo, mediante OAuth 2.0, JWT).
  • Autorización: Determinar qué puede hacer ese usuario/cliente.
  • TLS/HTTPS obligatorio para APIs públicas.
  • Políticas de rate limiting y throttling para prevenir abuso.
  • Sanitización de entradas, validación de esquemas, uso de CORS (cuando proceda).

Protocolos y formatos alternativos

  • Más allá de REST, SOAP y GraphQL, hay otros enfoques:
    • RPC con formatos binarios: gRPC + Protocol Buffers (alto rendimiento en microservicios internos).
    • WebSockets para comunicación bidireccional contínua (chat, colaboración en tiempo real).
    • HTTP/2 o HTTP/3 para mejorar multiplexado y latencia.
  • Formatos de datos: JSON, XML, YAML, o binarios (Protocol Buffers, MessagePack).

Contratos de API, esquemas y generación de código

  • Una especificación como OpenAPI Specification (OAS) describe rutas, parámetros, respuestas, esquemas de datos. :contentReference[oaicite:10]{index=10}
  • Se puede generar automáticamente:
    • Documentación interactiva (como Swagger UI) :contentReference[oaicite:12]{index=12}
    • SDKs cliente en varios lenguajes.
    • Validación de solicitudes/respuestas contra el contrato.
  • Importante para lograr coherencia entre servidor, cliente y documentación.

Arquitecturas basadas en microservicios y APIs internas

  • En una arquitectura de microservicios:
    • Las APIs internas pueden comunicarse mediante REST, GraphQL, eventos o colas de mensajes.
    • Se suele usar un API Gateway para exponer un “frente unificado” al exterior.
    • Considerar desacoplamiento, tolerancia a fallos, fallbacks, circuit breaker (patrón de resiliencia).
  • Importante gestionar la observabilidad: logs distribuidos, trazas (Distributed Tracing), métricas (latencia, fallo), alertas.

Versionado y compatibilidad

  • Versionar tu API ayuda a evitar romper clientes cuando cambias la lógica.
    • Estrategias: rutas (/v1), encabezados (Accept), parámetros de consulta (version=).
  • Mantener backward‐compatibility siempre que sea posible: agregar campos nuevos opcionalmente, no eliminar existentes sin aviso.

Errores, respuestas y consistencia

  • Respuestas consistentes: cuerpo estructurado de errores, códigos HTTP correctos (400, 401, 404, 500, etc).
  • Ejemplo de estructura de error:
	{
		"error": {
			"code": "INVALID_PARAMETER",
			"message": "El parámetro ‘email’ debe ser válido",
			"parameter": "email"
		}
	}
	```


- Documentar claramente qué errores puede devolver tu API y en qué condiciones.

### Automatización, testing y CI/CD
- Automatizar tests de integración de APIs: asegurar que los endpoints funcionen como se espera.  
- Integrar pruebas de rendimiento/carga (como con JMeter) para medir escalabilidad.  
- Monitorear en producción: latencia, errores, uso de recursos, cumplimiento de SLA.  
- Desplegar mediante pipelines de CI/CD: asegúrate de que al hacer una nueva versión se ejecuten tests, validación de contrato, rollback en caso de fallo.

### Tendencias y retos actuales
- APIs basadas en eventos (Event-driven). En lugar de solo peticiones, los servicios emiten eventos que otros consumen.  
- API First design: definir el contrato (OpenAPI) antes de implementar.  
- Integración con arquitectura serverless o funciones como servicio (FaaS).  
- Documentación generada automáticamente, “docs as code”, esquemas versionados.  
- Uso de Inteligencia Artificial para generar y mantener APIs/documentación.  
- Retos de gobernanza: múltiples microservicios, gran número de APIs internas/expuestas, control de políticas, seguridad, costes.

## Resumen ampliado
Esta ampliación aborda aspectos que facilitan la creación, mantenimiento y operación de APIs en entornos reales y complejos: desde diseño avanzado, operación, escalabilidad, seguridad, hasta gobernanza y futuras direcciones. Añade un marco más completo para que la nota en Obsidian tenga también los “aspectos de producción” que muchas veces se pasan por alto.

# API — Extensión Avanzada  

### API Gateway y patrones de integración
- **API Gateway**  
	- Es el punto de entrada único para todas las peticiones hacia los microservicios.  
	- Funciones clave: autenticación centralizada, limitación de tráfico, compresión, enrutamiento, logging, agregación de respuestas y control de versiones.  
	- Ejemplos: **Kong**, **NGINX**, **Traefik**, **Apigee**, **AWS API Gateway**, **Istio Ingress**.  
- **Patrones comunes**  
	- *Backend for Frontend (BFF)*: API específica para un tipo de cliente (móvil, web, IoT).  
	- *API Composition*: combinar varias APIs internas en una sola respuesta externa.  
	- *Service Mesh*: delegar la comunicación entre microservicios a un plano de datos (Istio, Linkerd).  
	- *Circuit Breaker*: proteger de cascadas de errores mediante límites de reintentos o respuestas por defecto.

---

### Observabilidad y monitoreo
- **Logs estructurados**: emitir en formato JSON con campos estándar (`timestamp`, `service`, `trace_id`, `status`, etc.).  
- **Métricas**: latencia, throughput, tasa de error, tamaño de payload, tiempos de respuesta por endpoint.  
- **Trazas distribuidas**: con sistemas como **OpenTelemetry**, **Jaeger** o **Zipkin** para seguir peticiones entre microservicios.  
- **Dashboards**: Prometheus + Grafana para visualizar métricas.  
- **Alertas**: definir umbrales de rendimiento, errores 5xx o tiempos de respuesta elevados.

---

### Gobernanza y control de versiones
- **Catálogo de APIs**: repositorio central que lista todas las APIs disponibles, sus propietarios, versiones, esquemas y políticas.  
- **Políticas de publicación**: definir quién puede exponer nuevas APIs o modificar existentes.  
- **Control de acceso**: integración con IAM (Identity & Access Management).  
- **Deprecación controlada**: anunciar cambios con tiempo, ofrecer periodo de coexistencia, automatizar eliminación de endpoints antiguos.  

---

### Estrategias de diseño de contrato
- **Design-first (API First)**: escribir la especificación OpenAPI antes del código, validando el diseño con clientes internos.  
- **Code-first**: generar la especificación a partir del código de los endpoints existentes.  
- **Hybrid approach**: sincronizar contrato y código en pipelines automáticos.  
- **Contratos como fuente de verdad**: centralizar validaciones, generación de SDKs y documentación a partir de un solo esquema.  

---

### Testing avanzado de APIs
- **Tipos de pruebas**  
	- *Unitarias*: validan controladores y lógica interna.  
	- *Integración*: verifican dependencias con bases de datos o servicios externos.  
	- *Contract testing*: verifica que cliente y servidor cumplen el contrato (con herramientas como **Pact**).  
	- *Smoke testing*: comprobar que las rutas principales responden tras despliegue.  
	- *End-to-end*: flujo completo del usuario o consumidor.  
- **Automatización**  
	- Integrar tests en CI/CD.  
	- Generar datos de prueba realistas.  
	- Analizar cobertura por endpoint.  

---

### Seguridad avanzada
- **OAuth 2.0 / OpenID Connect**: autenticación y autorización delegada, tokens de acceso y refresh.  
- **JWT (JSON Web Token)**: portadores de identidad firmados que permiten autenticación sin estado.  
- **API Keys y scopes**: control de permisos granular.  
- **HMAC / firmas**: verificación de integridad en webhooks.  
- **CORS avanzado**: definir orígenes, métodos y cabeceras permitidos; evitar exposición excesiva.  
- **Auditoría y trazabilidad**: registrar quién accede a qué endpoint y cuándo.  
- **Rate-limiting dinámico**: basado en roles o planes de suscripción.  

---

### APIs en tiempo real
- **WebSockets**: comunicación persistente full-duplex entre cliente y servidor.  
- **Server-Sent Events (SSE)**: flujo unidireccional desde servidor hacia cliente.  
- **gRPC streaming**: envío continuo de mensajes binarios de alto rendimiento.  
- **MQTT / AMQP**: protocolos ligeros para IoT y mensajería en entornos distribuidos.  
- **Webhook**: mecanismo de *push* basado en HTTP; útil para notificaciones, integraciones externas y eventos.  

Ejemplo básico de webhook en Flask:


```python
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def receive_webhook():
	data = request.json
	print("Evento recibido:", data)
	return '', 204

`


Versionado semántico y evolución

  • Versionado semántico (semver) aplicado a APIs:

    • Cambios incompatibles → versión mayor (v2).
    • Nuevas funcionalidades compatibles → menor (v1.1).
    • Parches o correcciones → parche (v1.0.1).
  • Gestión de compatibilidad

    • Feature flags para activar gradualmente nuevas versiones.
    • Gateways que enrutan por versión.
    • Documentación que indique diferencias por versión.

API Analytics y métricas de negocio

  • Analizar datos de consumo:

    • Endpoints más usados, usuarios activos, tasa de error.
    • Impacto en ingresos (para APIs comerciales).
  • Correlacionar métricas técnicas con métricas de negocio: tiempo medio de respuesta vs retención de usuarios.
  • Uso de herramientas de API Analytics: Kong Enterprise, Apigee, AWS CloudWatch, Elastic Stack.

APIs comerciales y monetización

  • Modelos de negocio

    • Freemium: uso limitado gratuito, pago por volumen.
    • Subscription: tarifa fija mensual o anual.
    • Pay-per-use: cobro por llamada o recurso consumido.
  • Gestión de clientes

    • Portales de desarrolladores con registro, documentación y claves de acceso.
    • Paneles de facturación y cuotas.
  • Integración con pasarelas de pago y sistemas de facturación automáticos.


API Design Patterns

  • Collection Pattern: recursos representados como colecciones y elementos (/users → lista, /users/{id} → detalle).
  • Sub-resources: reflejar jerarquías (/users/{id}/orders).
  • Batching: varias operaciones en una sola petición.
  • Pagination: limit, offset, nextCursor.
  • Filtering y sorting: ?status=active&sort=-date.
  • Partial update (PATCH): modificación parcial del recurso.
  • Error-envelope pattern: estructura consistente de errores.
  • Hypermedia links (HATEOAS): respuestas con enlaces a operaciones relacionadas.

API Documentation as Code

  • Mantener la documentación junto al código fuente.
  • Validación automática en cada commit (linting de OpenAPI).
  • Generación de portales estáticos (ReDoc, Swagger UI, Docusaurus).
  • Versionado de documentación en paralelo al código.
  • Pruebas automatizadas que comparen ejemplos documentados con respuestas reales.

Seguridad de transporte y cifrado

  • TLS obligatorio para todas las conexiones externas.
  • Renovación y rotación automática de certificados (ACME, Let’s Encrypt).
  • Validación mutua (mTLS) en entornos internos sensibles.
  • Protección frente a ataques comunes:

    • Replay Attack: tokens de un solo uso o timestamps.
    • Injection: validación estricta de entrada.
    • Cross-Site Scripting (XSS) y CSRF: cabeceras seguras y tokens.

Integraciones híbridas y legacy

  • Adaptadores (API Adapters) que exponen sistemas antiguos como REST/GraphQL.
  • Uso de API Orchestration Layers para integrar múltiples backends dispares.
  • API Facades: crear interfaces simplificadas sobre servicios complejos.
  • Migración progresiva de SOAP a REST o GraphQL mediante gateways híbridos.

Futuro de las APIs

  • Declarative APIs: definir comportamiento en YAML/JSON, ejecutado por plataformas sin servidor.
  • Machine-Generated APIs: creación y actualización automática mediante IA.
  • Zero-code / Low-code APIs: plataformas que permiten exponer datos sin escribir código.
  • Interoperabilidad semántica: uso de vocabularios y esquemas compartidos (JSON-LD, Schema.org).
  • API Contracts Validation at Runtime: validar en producción que las respuestas cumplen el contrato.
  • Edge APIs: ejecución distribuida cerca del usuario (Cloudflare Workers, Vercel Edge).

Conclusión extendida

Esta ampliación cubre las capas de operación, gobierno, observabilidad, seguridad avanzada, monetización, diseño y tendencias futuras. Con ello, el documento ofrece una visión integral del ciclo de vida completo de una API moderna: diseño, implementación, despliegue, mantenimiento y evolución, con los principales patrones y tecnologías de referencia hasta 2025.

Diseño de Patrones y Protocolos API


Introducción

El diseño de patrones y protocolos en una API define cómo se comunican los sistemas, cómo se estructuran los recursos y qué convenciones garantizan interoperabilidad y mantenibilidad.
Un buen diseño implica coherencia, previsibilidad, seguridad y escalabilidad a largo plazo.

Los patrones de diseño proporcionan soluciones comunes a problemas recurrentes en el desarrollo y operación de APIs, mientras que los protocolos definen las reglas técnicas de la comunicación.


1. Patrones de diseño de API

1.1. Patrones estructurales

  • Resource Pattern
    • Cada entidad se representa como un recurso con un identificador único (URI).
    • Ejemplo: /users, /users/{id}, /orders/{orderId}.
    • Usado en REST y GraphQL (a nivel de tipo).
  • Collection Pattern
    • Agrupa recursos relacionados bajo una colección.
    • Permite operaciones CRUD sobre conjuntos.
    • Ejemplo:
      • GET /users → lista
      • POST /users → crear
      • GET /users/{id} → detalle
  • Subresource Pattern
    • Representa jerarquías o dependencias.
    • Ejemplo: /users/{id}/orders.
    • Evita exponer relaciones implícitas mediante consultas complejas.
  • Envelope Pattern
    • Uniforma respuestas dentro de un contenedor predecible.
    • Ejemplo:
		{
			"status": "success",
			"data": {...},
			"errors": []
		}
		```


---

### 1.2. Patrones de comunicación

- **Request-Response**  
	- Clásico intercambio síncrono cliente-servidor.  
	- Base de REST, SOAP y gRPC unary.  

- **Publish/Subscribe**  
	- Desacopla emisores y receptores mediante eventos.  
	- Usado en APIs de tipo *event-driven* o Webhooks.  

- **Streaming**  
	- Envío continuo de datos (gRPC streaming, WebSockets, SSE).  
	- Ideal para tiempo real, monitoreo o IoT.

- **CQRS (Command Query Responsibility Segregation)**  
	- Separar comandos (modifican estado) de consultas (solo lectura).  
	- Reduce acoplamiento y mejora escalabilidad.

---

### 1.3. Patrones de versionado

- **URI versioning**  
	- `/api/v1/...`  
- **Header versioning**  
	- `Accept: application/vnd.api+json; version=2`  
- **Query versioning**  
	- `?version=3`  
- **Backward compatibility**  
	- Evitar romper clientes; añadir campos nuevos sin eliminar antiguos.  

---

### 1.4. Patrones de agregación y composición

- **API Composition**  
	- Combina respuestas de varios servicios en uno solo.  
	- Ejemplo: un endpoint `/dashboard` que une datos de `/users` y `/orders`.  

- **Backend for Frontend (BFF)**  
	- API adaptada a un tipo de cliente (web, móvil, IoT).  
	- Mejora rendimiento y reduce lógica en el frontend.  

- **GraphQL Pattern**  
	- Permite consultas personalizadas, combinando múltiples recursos en una sola llamada.  
	- Se basa en un esquema tipado que describe los datos disponibles.  

---

### 1.5. Patrones de resiliencia

- **Circuit Breaker**  
	- Previene cascadas de fallos cortando llamadas a servicios no disponibles.  
- **Retry Pattern**  
	- Reintenta peticiones fallidas con backoff exponencial.  
- **Timeout Pattern**  
	- Define tiempos máximos de espera por respuesta.  
- **Fallback Pattern**  
	- Usa una respuesta por defecto cuando un servicio falla.  

---

### 1.6. Patrones de seguridad

- **Token-based Auth**  
	- Uso de JWT u OAuth 2.0 para autenticación sin estado.  
- **Rate Limiting Pattern**  
	- Límite de peticiones por cliente o IP.  
- **mTLS (Mutual TLS)**  
	- Autenticación mutua entre servicios internos.  
- **Input Validation Pattern**  
	- Validación estricta en cada punto de entrada (schemas).  

---

## 2. Protocolos de API

### 2.1. REST
- Protocolo basado en HTTP, ligero y ampliamente adoptado.  
- Usa métodos estándar (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`).  
- Datos generalmente en formato JSON.  
- Ventajas: simplicidad, cacheo, soporte universal.  
- Desventajas: acoplamiento débil entre cliente y servidor, sobre/infra-fetching.

---

### 2.2. SOAP
- Basado en XML, formal y con contratos definidos mediante WSDL.  
- Orientado a entornos corporativos o regulados.  
- Permite transporte sobre HTTP, SMTP u otros protocolos.  
- Soporta transacciones complejas y seguridad WS-*.

---

### 2.3. [GraphQL](/backend/graphql/)
- Permite al cliente definir la estructura exacta de la respuesta.  
- Un solo endpoint (`/graphql`) maneja múltiples consultas y mutaciones.  
- Ventajas: evita overfetching/underfetching.  
- Desventajas: caching complejo y consultas costosas si no se limitan.  

---

### 2.4. [gRPC](/backend/grpc/)
- Framework RPC basado en HTTP/2 y Protocol Buffers.  
- Comunicación binaria, compacta y de alto rendimiento.  
- Ideal para comunicación entre microservicios internos.  
- Soporta streaming bidireccional.  

Ejemplo básico de definición `.proto`:


```proto
syntax = "proto3";

service UserService {
	rpc GetUser (UserRequest) returns (UserResponse);
}

message UserRequest {
	int32 id = 1;
}

message UserResponse {
	string name = 1;
	string email = 2;
}

`


2.5. WebSockets

  • Protocolo full-duplex sobre TCP para comunicación en tiempo real.
  • Mantiene una conexión abierta entre cliente y servidor.
  • Ideal para chats, notificaciones y colaboración simultánea.

2.6. Server-Sent Events (SSE)

  • Permite al servidor enviar flujos unidireccionales continuos al cliente.
  • Útil para actualizaciones en vivo o dashboards.

2.7. MQTT y AMQP

  • Protocolos ligeros para IoT y mensajería asincrónica.
  • MQTT se basa en el modelo publish/subscribe.
  • AMQP proporciona colas, enrutamiento y confirmación de entrega.

3. Patrones de interoperabilidad

  • HATEOAS (Hypermedia as the Engine of Application State)

    • Incluye enlaces en las respuestas que describen las posibles acciones siguientes.
    • Ejemplo:

json { "id": 1, "name": "Eduardo", "links": [ {"rel": "self", "href": "/users/1"}, {"rel": "orders", "href": "/users/1/orders"} ] }

  • Content Negotiation

    • Cliente y servidor acuerdan el formato (JSON, XML, YAML) mediante encabezados Accept y Content-Type.
  • Idempotencia

    • Repetir una misma operación produce siempre el mismo resultado (importante para PUT y DELETE).
  • Statelessness

    • Cada solicitud contiene todo el contexto necesario, sin depender del estado del servidor.

4. Patrones de evolución y gobernanza

  • Deprecation Strategy

    • Notificar y documentar endpoints obsoletos.
    • Mantener periodo de compatibilidad.
  • Schema Registry

    • Control central de los contratos y versiones de API.
  • API Linter / Validator

    • Analiza convenciones, consistencia y cumplimiento de estándares (por ejemplo, Spectral, OpenAPI Lint).
  • Observabilidad

    • Implementar trazas, logs estructurados y métricas por endpoint.

5. Comparativa de protocolos

Protocolo Transporte Formato Orientación Rendimiento Complejidad Ideal para
REST HTTP/1.1 JSON Recursos Medio Baja APIs públicas
SOAP HTTP/SMTP XML Servicios Medio Alta Entornos corporativos
GraphQL HTTP JSON Consultas Medio Media Frontends dinámicos
gRPC HTTP/2 Binario RPC Alta Media Microservicios internos
WebSockets TCP Texto/Binario Eventos Alta Media Tiempo real
MQTT TCP Binario Pub/Sub Muy alta Baja IoT
AMQP TCP Binario Mensajería Alta Alta Integraciones empresariales

Conclusión

El diseño de una API moderna requiere seleccionar el protocolo adecuado según el caso de uso, junto con patrones de diseño que garanticen robustez, mantenibilidad y compatibilidad futura. REST y GraphQL dominan el panorama web, mientras que gRPC, WebSockets y MQTT amplían las posibilidades hacia entornos distribuidos, tiempo real y sistemas embebidos. Adoptar patrones de versionado, resiliencia y seguridad permite construir APIs predecibles, estables y escalables en cualquier ecosistema.