APIs y Microservicios: Construyendo Arquitecturas Escalables y Mantenibles

En el desarrollo moderno, las APIs (Application Programming Interfaces) y las arquitecturas de microservicios son fundamentales para crear sistemas escalables, mantenibles y resilientes. En V1tr0, diseñamos e implementamos arquitecturas backend que soportan el crecimiento de tu negocio.

¿Qué es una API?

Una API es un conjunto de definiciones y protocolos que permiten que diferentes aplicaciones se comuniquen entre sí. Es el contrato entre el cliente y el servidor que define cómo solicitar y recibir datos.

Tipos de APIs

REST (Representational State Transfer)

El estándar más popular para APIs web:

Características:

• Stateless: Sin estado entre requests
• HTTP methods: GET, POST, PUT, DELETE, PATCH
• Resources: URLs representan recursos
• JSON/XML: Formatos de respuesta
• Cache-friendly: Optimización de caché

Ejemplo de endpoints REST:

1GET    /api/users           # Obtener todos los usuarios
2GET    /api/users/:id       # Obtener un usuario
3POST   /api/users           # Crear usuario
4PUT    /api/users/:id       # Actualizar usuario completo
5PATCH  /api/users/:id       # Actualizar usuario parcial
6DELETE /api/users/:id       # Eliminar usuario

GraphQL

Query language para APIs desarrollado por Facebook:

Características:

• Single endpoint: Un solo punto de entrada
• Client-specified queries: Cliente solicita exactamente lo que necesita
• No over-fetching: Sin datos innecesarios
• No under-fetching: Una query para múltiples recursos
• Strongly typed: Schema con tipos definidos

Ejemplo de query GraphQL:

graphql
1query {
2  user(id: "123") {
3    name
4    email
5    posts {
6      title
7      comments {
8        text
9        author {
10          name
11        }
12      }
13    }
14  }
15}

gRPC

Framework RPC de alto rendimiento:

Características:

• Protocol Buffers: Serialización binaria
• HTTP/2: Multiplexing, server push
• Bidirectional streaming: Comunicación en ambas direcciones
• Language agnostic: Multi-lenguaje
• High performance: Muy eficiente

Caso de uso: Comunicación entre microservicios internos.

WebSockets

Comunicación bidireccional en tiempo real:

Características:

• Full-duplex: Cliente y servidor pueden enviar simultáneamente
• Persistent connection: Conexión mantenida
• Low latency: Latencia mínima
• Real-time: Chat, notificaciones, gaming

Diseño de APIs REST

Principios RESTful

1. Naming Conventions

URLs claras y consistentes:

1✅ Correcto:
2GET /api/v1/users
3GET /api/v1/users/123/posts
4
5❌ Incorrecto:
6GET /api/v1/getAllUsers
7GET /api/v1/user_posts?userId=123

Reglas:

• Plural nouns: Usar plurales para recursos
• Lowercase: Todo en minúsculas
• Hyphens: Guiones para separar palabras
• No trailing slashes: Sin barra final
• Versioning: Incluir versión de API

2. HTTP Status Codes

Usar códigos apropiados:

12xx - Success
2  200 OK - Request exitoso
3  201 Created - Recurso creado
4  204 No Content - Éxito sin contenido
5
63xx - Redirection
7  301 Moved Permanently
8  304 Not Modified
9
104xx - Client Errors
11  400 Bad Request - Request inválido
12  401 Unauthorized - No autenticado
13  403 Forbidden - No autorizado
14  404 Not Found - Recurso no existe
15  422 Unprocessable Entity - Validación fallida
16  429 Too Many Requests - Rate limit
17
185xx - Server Errors
19  500 Internal Server Error
20  502 Bad Gateway
21  503 Service Unavailable

3. Request/Response Structure

Formato consistente:

json
1// Success Response
2{
3  "success": true,
4  "data": {
5    "id": "123",
6    "name": "John Doe",
7    "email": "john@example.com"
8  },
9  "metadata": {
10    "timestamp": "2025-02-10T10:00:00Z",
11    "version": "1.0"
12  }
13}
14
15// Error Response
16{
17  "success": false,
18  "error": {
19    "code": "VALIDATION_ERROR",
20    "message": "Email is required",
21    "details": [
22      {
23        "field": "email",
24        "message": "Email cannot be empty"
25      }
26    ]
27  }
28}

4. Pagination

Para listas grandes:

json
1GET /api/users?page=2&limit=20
2
3{
4  "data": [...],
5  "pagination": {
6    "page": 2,
7    "limit": 20,
8    "total": 100,
9    "totalPages": 5,
10    "hasNext": true,
11    "hasPrev": true
12  }
13}

5. Filtering, Sorting, Searching

1# Filtering
2GET /api/users?status=active&role=admin
3
4# Sorting
5GET /api/users?sort=-createdAt,name
6
7# Searching
8GET /api/users?search=john
9
10# Combined
11GET /api/users?status=active&sort=-createdAt&limit=10

Authentication & Authorization

JWT (JSON Web Tokens)

Token-based authentication:

typescript
1// Generate token
2import jwt from 'jsonwebtoken';
3
4const token = jwt.sign(
5  { userId: user.id, email: user.email },
6  process.env.JWT_SECRET,
7  { expiresIn: '7d' }
8);
9
10// Verify token
11const decoded = jwt.verify(token, process.env.JWT_SECRET);

Headers:

1Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

OAuth 2.0

Delegated authorization:

Flows:

• Authorization Code: Para apps con backend
• Implicit: Para SPAs (deprecated)
• Client Credentials: Machine-to-machine
• Password Grant: Username/password (legacy)

API Keys

Simple pero efectivo para APIs públicas:

1X-API-Key: your-api-key-here

Rate Limiting

Proteger la API de abuso:

typescript
1import rateLimit from 'express-rate-limit';
2
3const limiter = rateLimit({
4  windowMs: 15 * 60 * 1000, // 15 minutes
5  max: 100, // limit each IP to 100 requests per windowMs
6  message: 'Too many requests from this IP'
7});
8
9app.use('/api/', limiter);

Response headers:

1X-RateLimit-Limit: 100
2X-RateLimit-Remaining: 45
3X-RateLimit-Reset: 1644501234

API Documentation

OpenAPI (Swagger)

Especificación estándar para APIs REST:

yaml
1openapi: 3.0.0
2info:
3  title: User API
4  version: 1.0.0
5paths:
6  /users:
7    get:
8      summary: Get all users
9      parameters:
10        - name: page
11          in: query
12          schema:
13            type: integer
14      responses:
15        '200':
16          description: Successful response
17          content:
18            application/json:
19              schema:
20                type: array
21                items:
22                  $ref: '#/components/schemas/User'
23components:
24  schemas:
25    User:
26      type: object
27      properties:
28        id:
29          type: string
30        name:
31          type: string
32        email:
33          type: string

Herramientas:

• Swagger UI: Interfaz interactiva
• Redoc: Documentación elegante
• Postman: Testing y documentación

Arquitectura de Microservicios

¿Qué Son los Microservicios?

Arquitectura que estructura una aplicación como colección de servicios pequeños, independientes y desplegables.

Características

1. Independently deployable: Despliegue independiente
2. Loosely coupled: Bajo acoplamiento
3. Organized around business capabilities: Por capacidad de negocio
4. Owned by small teams: Equipos pequeños
5. Polyglot: Diferentes tecnologías por servicio

Monolito vs Microservicios

Monolito

1┌─────────────────────────────────────┐
2│         Single Application          │
3│                                     │
4│  ┌──────┐  ┌────┐  ┌─────────┐   │
5│  │ Auth │  │ User│  │ Payment │   │
6│  └──────┘  └────┘  └─────────┘   │
7│                                     │
8│      Single Database                │
9└─────────────────────────────────────┘

Ventajas:

• Desarrollo simple inicial
• Testing más fácil
• Despliegue directo

Desventajas:

• Escalado todo o nada
• Coupling alto
• Deploy riesgoso

Microservicios

1┌─────────┐   ┌──────────┐   ┌─────────────┐
2│  Auth   │   │   User   │   │  Payment    │
3│ Service │   │ Service  │   │  Service    │
4│         │   │          │   │             │
5│   DB    │   │    DB    │   │     DB      │
6└─────────┘   └──────────┘   └─────────────┘

Ventajas:

• Escalado independiente
• Deploy independiente
• Tecnología flexible
• Fallas aisladas

Desventajas:

• Complejidad operacional
• Testing distribuido
• Data consistency

Patrones de Microservicios

API Gateway

Punto de entrada único:

1Client → API Gateway → [Auth Service]
2                    → [User Service]
3                    → [Order Service]

Responsabilidades:

• Routing: Enrutamiento de requests
• Authentication: Verificación de identidad
• Rate limiting: Control de tasa
• Load balancing: Balanceo de carga
• Response aggregation: Agregación de respuestas

Herramientas:

• Kong: Open source, feature-rich
• AWS API Gateway: Managed service
• Nginx: Reverse proxy
• Traefik: Cloud-native

Service Discovery

Registro y descubrimiento dinámico:

Service Registry:

• Consul: HashiCorp, multi-DC
• Eureka: Netflix OSS
• etcd: Kubernetes native
• Zookeeper: Apache, mature

Pattern:

1Service → Register → Service Registry
2Client → Discover → Service Registry → Service Address

Circuit Breaker

Prevenir fallas en cascada:

typescript
1import CircuitBreaker from 'opossum';
2
3const options = {
4  timeout: 3000,
5  errorThresholdPercentage: 50,
6  resetTimeout: 30000
7};
8
9const breaker = new CircuitBreaker(callExternalService, options);
10
11breaker.fallback(() => ({ cached: true, data: cachedData }));
12
13breaker.fire(params)
14  .then(result => console.log(result))
15  .catch(err => console.error(err));

Estados:

• Closed: Normal, requests pasan
• Open: Fallas detectadas, requests bloqueados
• Half-Open: Probando recuperación

Saga Pattern

Transacciones distribuidas:

Choreography-based:

1Order Service → Order Created Event → Inventory Service
2Inventory Service → Inventory Reserved → Payment Service
3Payment Service → Payment Processed → Shipping Service

Orchestration-based:

1Saga Orchestrator → Create Order → Order Service
2                 → Reserve Inventory → Inventory Service
3                 → Process Payment → Payment Service
4                 → Ship Order → Shipping Service

Event Sourcing

Almacenar cambios como eventos:

typescript
1// Events
2class OrderCreated {
3  constructor(orderId, userId, items) {
4    this.orderId = orderId;
5    this.userId = userId;
6    this.items = items;
7    this.timestamp = Date.now();
8  }
9}
10
11class OrderPaid {
12  constructor(orderId, amount) {
13    this.orderId = orderId;
14    this.amount = amount;
15    this.timestamp = Date.now();
16  }
17}
18
19// Event Store
20const events = [
21  new OrderCreated('123', 'user1', [items]),
22  new OrderPaid('123', 99.99)
23];
24
25// Rebuild state
26const order = events.reduce((state, event) => {
27  return applyEvent(state, event);
28}, {});

CQRS (Command Query Responsibility Segregation)

Separar lectura y escritura:

1Commands (Write) → Write Model → Event Store
2                                      ↓
3Queries (Read) ← Read Model ← Event Handlers

Beneficios:

• Optimized reads: Queries optimizadas
• Scalability: Escalar lectura/escritura independiente
• Flexibility: Diferentes modelos

Communication Patterns

Synchronous (HTTP/gRPC)

Request-response directo:

typescript
1// REST
2const user = await fetch('http://user-service/api/users/123')
3  .then(res => res.json());
4
5// gRPC
6const user = await userClient.getUser({ id: '123' });

Pros: Simple, inmediato Cons: Acoplamiento temporal, fallas en cascada

Asynchronous (Message Queue)

Comunicación desacoplada:

typescript
1// Publish
2await messageQueue.publish('user.created', {
3  userId: '123',
4  email: 'user@example.com'
5});
6
7// Subscribe
8messageQueue.subscribe('user.created', async (message) => {
9  await sendWelcomeEmail(message.email);
10});

Message Brokers:

• RabbitMQ: AMQP, feature-rich
• Apache Kafka: High throughput, event streaming
• AWS SQS: Managed, simple
• Redis Pub/Sub: Simple, fast

Pros: Desacoplamiento, resiliencia Cons: Eventual consistency, complejidad

Implementación Práctica

Stack Tecnológico V1tr0

Backend Frameworks

Node.js + Express:

typescript
1import express from 'express';
2import { createUserHandler } from './handlers';
3
4const app = express();
5
6app.use(express.json());
7
8app.post('/api/users', createUserHandler);
9
10app.listen(3000, () => {
11  console.log('Server running on port 3000');
12});

Node.js + Fastify:

typescript
1import fastify from 'fastify';
2
3const server = fastify({ logger: true });
4
5server.post('/api/users', {
6  schema: {
7    body: {
8      type: 'object',
9      required: ['email'],
10      properties: {
11        email: { type: 'string', format: 'email' }
12      }
13    }
14  }
15}, async (request, reply) => {
16  return { id: '123', email: request.body.email };
17});
18
19await server.listen({ port: 3000 });

NestJS:

typescript
1import { Controller, Get, Post, Body } from '@nestjs/common';
2
3@Controller('users')
4export class UsersController {
5  @Post()
6  create(@Body() createUserDto: CreateUserDto) {
7    return this.usersService.create(createUserDto);
8  }
9
10  @Get()
11  findAll() {
12    return this.usersService.findAll();
13  }
14}

Databases

PostgreSQL: Relational data MongoDB: Document store Redis: Caching, sessions Elasticsearch: Search, analytics

Message Queues

Bull (Redis-based):

typescript
1import Queue from 'bull';
2
3const emailQueue = new Queue('email', {
4  redis: { host: 'localhost', port: 6379 }
5});
6
7// Producer
8await emailQueue.add({ to: 'user@example.com', subject: 'Welcome' });
9
10// Consumer
11emailQueue.process(async (job) => {
12  await sendEmail(job.data);
13});

Testing de APIs

Unit Tests

typescript
1import { describe, it, expect } from 'vitest';
2import { createUser } from './user.service';
3
4describe('UserService', () => {
5  it('should create a user', async () => {
6    const user = await createUser({
7      email: 'test@example.com',
8      name: 'Test User'
9    });
10    
11    expect(user).toHaveProperty('id');
12    expect(user.email).toBe('test@example.com');
13  });
14});

Integration Tests

typescript
1import request from 'supertest';
2import app from './app';
3
4describe('POST /api/users', () => {
5  it('should create a user', async () => {
6    const response = await request(app)
7      .post('/api/users')
8      .send({
9        email: 'test@example.com',
10        name: 'Test User'
11      })
12      .expect(201);
13    
14    expect(response.body.data).toHaveProperty('id');
15  });
16});

Contract Testing

typescript
1import { Pact } from '@pact-foundation/pact';
2
3const provider = new Pact({
4  consumer: 'UserService',
5  provider: 'AuthService'
6});
7
8it('should authenticate user', async () => {
9  await provider.addInteraction({
10    state: 'user exists',
11    uponReceiving: 'a request to authenticate',
12    withRequest: {
13      method: 'POST',
14      path: '/auth',
15      body: { email: 'user@example.com' }
16    },
17    willRespondWith: {
18      status: 200,
19      body: { token: 'abc123' }
20    }
21  });
22  
23  // Test implementation
24});

Monitoring & Observability

Logging

Structured logging:

typescript
1import winston from 'winston';
2
3const logger = winston.createLogger({
4  format: winston.format.json(),
5  defaultMeta: { service: 'user-service' },
6  transports: [
7    new winston.transports.File({ filename: 'error.log', level: 'error' }),
8    new winston.transports.File({ filename: 'combined.log' })
9  ]
10});
11
12logger.info('User created', { userId: '123', email: 'user@example.com' });

Metrics

Application metrics:

typescript
1import client from 'prom-client';
2
3const httpRequestDuration = new client.Histogram({
4  name: 'http_request_duration_seconds',
5  help: 'Duration of HTTP requests in seconds',
6  labelNames: ['method', 'route', 'status']
7});
8
9app.use((req, res, next) => {
10  const start = Date.now();
11  res.on('finish', () => {
12    const duration = (Date.now() - start) / 1000;
13    httpRequestDuration
14      .labels(req.method, req.route.path, res.statusCode)
15      .observe(duration);
16  });
17  next();
18});

Distributed Tracing

typescript
1import { trace } from '@opentelemetry/api';
2
3const tracer = trace.getTracer('user-service');
4
5async function createUser(data) {
6  const span = tracer.startSpan('createUser');
7  
8  try {
9    // Business logic
10    span.setAttribute('user.email', data.email);
11    const user = await db.users.create(data);
12    span.setStatus({ code: SpanStatusCode.OK });
13    return user;
14  } catch (error) {
15    span.recordException(error);
16    span.setStatus({ code: SpanStatusCode.ERROR });
17    throw error;
18  } finally {
19    span.end();
20  }
21}

Best Practices

1. API Versioning

Mantener compatibilidad:

1/api/v1/users
2/api/v2/users

2. Idempotency

Operaciones repetibles:

typescript
1app.post('/api/payments', async (req, res) => {
2  const idempotencyKey = req.headers['idempotency-key'];
3  
4  // Check if already processed
5  const existing = await redis.get(idempotencyKey);
6  if (existing) {
7    return res.json(JSON.parse(existing));
8  }
9  
10  const result = await processPayment(req.body);
11  await redis.setex(idempotencyKey, 86400, JSON.stringify(result));
12  
13  res.json(result);
14});

3. Health Checks

typescript
1app.get('/health', async (req, res) => {
2  const health = {
3    status: 'ok',
4    timestamp: Date.now(),
5    uptime: process.uptime(),
6    checks: {
7      database: await checkDatabase(),
8      redis: await checkRedis(),
9      messageQueue: await checkMQ()
10    }
11  };
12  
13  const status = Object.values(health.checks).every(v => v === 'ok')
14    ? 200
15    : 503;
16  
17  res.status(status).json(health);
18});

4. Graceful Shutdown

typescript
1process.on('SIGTERM', async () => {
2  console.log('SIGTERM received, shutting down gracefully');
3  
4  server.close(async () => {
5    await db.close();
6    await messageQueue.close();
7    process.exit(0);
8  });
9  
10  // Force shutdown after 30s
11  setTimeout(() => {
12    console.error('Forced shutdown');
13    process.exit(1);
14  }, 30000);
15});

Conclusión

Las APIs bien diseñadas y las arquitecturas de microservicios son la base de sistemas modernos escalables y mantenibles. En V1tr0, combinamos las mejores prácticas de la industria con años de experiencia para crear backends robustos que soportan el crecimiento de tu negocio.

Desde el diseño de APIs RESTful hasta la implementación de arquitecturas de microservicios complejas, estamos equipados para enfrentar cualquier desafío técnico y entregar soluciones que realmente funcionan.

¿Listo para construir una arquitectura backend sólida? Hablemos sobre tu proyecto.