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:
    {
    	"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.




# omnivore api

```base
type: list
name: "Notas con #api en Omnivore"
order:
  - property: date_saved
    direction: desc
columns:
  - file.name
  - date_saved
filters:
  and:
    - file.inFolder("Omnivore")
    - file.hasTag("api", "API")
views:
  - type: table
    name: Table
    sort:
      - property: file.mtime
        direction: DESC