Modulo 01. HTTP, REST y principios de diseño de APIs

Objetivo del modulo

Comprender HTTP como protocolo base de las APIs web y aplicar principios REST para diseñar recursos, operaciones y respuestas con semantica consistente.

Resultados esperados

• Diferenciar metodo HTTP, recurso, endpoint y representacion.
• Elegir codigos de estado adecuados.
• Diseñar rutas RESTful legibles.
• Evitar errores frecuentes de semantica HTTP.

Desarrollo teorico

Toda API HTTP se apoya en el protocolo web. Antes de hablar de frameworks o microservicios hay que entender que una peticion HTTP tiene metodo, URI, cabeceras, cuerpo y semantica de respuesta. GET recupera representaciones, POST crea o desencadena procesamiento, PUT reemplaza, PATCH modifica parcialmente y DELETE elimina. No son simplemente verbos intercambiables; cada uno comunica intencion al cliente, a caches, proxies, herramientas y equipos humanos.

REST no es "usar JSON con HTTP". Es un estilo arquitectonico que enfatiza recursos identificables por URI, operaciones uniformes, ausencia de estado de sesion en el servidor para cada peticion y uso correcto del protocolo subyacente. En diseño cotidiano, esto suele traducirse a modelar bien los recursos: /users, /orders/123, /tickets/ABC-1/comments. Un anti-patron comun es usar rutas basadas en acciones para todo, como /createUser o /deleteServer, desperdiciando la semantica de HTTP.

Los codigos de estado tambien importan. 200 OK indica exito general; 201 Created es adecuado tras crear un recurso; 204 No Content encaja cuando la operacion fue correcta pero no devuelve cuerpo; 400 Bad Request refleja entrada invalida; 401 Unauthorized indica falta de autenticacion valida; 403 Forbidden significa que el cliente esta autenticado pero no tiene permiso; 404 Not Found expresa ausencia del recurso; 409 Conflict es util para colisiones de estado; 500 y familia indican problemas del lado servidor.

Diseñar bien una API significa tambien pensar en paginacion, filtrado, ordenacion y estructura de errores. Si /tickets puede devolver miles de elementos, necesita page, limit, cursores u otro mecanismo. Si la respuesta de error cambia en cada endpoint, el consumidor sufrira. Una API profesional debe ser predecible tanto en el camino feliz como cuando algo sale mal.

Ejemplo practico de API REST

Un diseño RESTful para un sistema de tickets ilustra las decisiones habituales:

# Listar tickets con filtros y paginacion
GET /api/v1/tickets?status=open&priority=high&page=1&limit=20
Accept: application/json
Authorization: Bearer eyJhbGci...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "TK-1042",
      "title": "Error en SSO corporativo",
      "status": "open",
      "priority": "high",
      "assignee": null,
      "createdAt": "2026-03-15T10:30:00Z"
    }
  ],
  "total": 87,
  "page": 1,
  "pageSize": 20
}

# Crear un ticket
POST /api/v1/tickets
Content-Type: application/json
Authorization: Bearer eyJhbGci...

{
  "title": "VPN no conecta desde la oficina de Madrid",
  "description": "Desde esta mañana varios usuarios reportan timeout al conectar la VPN.",
  "priority": "high"
}

HTTP/1.1 201 Created
Location: /api/v1/tickets/TK-1043
Content-Type: application/json

{
  "data": {
    "id": "TK-1043",
    "title": "VPN no conecta desde la oficina de Madrid",
    "status": "open",
    "priority": "high",
    "createdAt": "2026-03-27T09:15:00Z"
  }
}

# Cambiar estado parcialmente
PATCH /api/v1/tickets/TK-1043
Content-Type: application/json

{ "status": "in_progress", "assignedTo": "agent-007" }

HTTP/1.1 200 OK

# Eliminar un ticket
DELETE /api/v1/tickets/TK-1043

HTTP/1.1 204 No Content

Estructura de errores consistente

Una API profesional devuelve errores con formato predecible. El consumidor no deberia adivinar donde esta el mensaje de error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Datos de entrada invalidos",
    "details": {
      "title": "Debe tener al menos 5 caracteres",
      "priority": "Valor no permitido. Opciones: low, medium, high, critical"
    },
    "requestId": "req-abc123"
  }
}

Paginacion con cursores frente a offset

La paginacion por offset (page=3&limit=20) es simple pero se degrada en tablas grandes. La paginacion por cursor es mas eficiente porque no necesita contar filas anteriores:

# Paginacion por cursor
GET /api/v1/tickets?limit=20&after=TK-1040

{
  "data": [...],
  "pagination": {
    "hasNext": true,
    "nextCursor": "TK-1060"
  }
}

El cursor suele ser el ID o timestamp del ultimo elemento. Es mas resistente a inserciones concurrentes que el offset, porque no se desplazan posiciones cuando se añaden nuevos registros.

Contenido ampliado

• Cabeceras comunes como Content-Type, Accept y Authorization.
• Idempotencia y seguridad de metodos.
• Colecciones, subrecursos y acciones excepcionales.

Puntos clave

• HTTP no es solo transporte; aporta semantica.
• REST se apoya en recursos coherentes y operaciones uniformes.
• Los codigos de estado comunican resultado funcional y tecnico.
• Una API buena es predecible y consistente.

Checklist operativa

• Verificar que cada ruta modela un recurso real.
• Elegir metodo HTTP segun la intencion.
• Devolver codigos de estado alineados con el resultado.
• Diseñar respuestas de error consistentes.

Errores frecuentes

• Usar POST para cualquier operacion.
• Diseñar rutas basadas solo en verbos.
• Responder 200 incluso cuando hay error funcional.
• Ignorar paginacion en colecciones grandes.

Practica sugerida

Diseña una API de tickets con endpoints de listado, detalle, creacion, cambio de estado y comentarios, indicando metodos y codigos de estado esperados.

Preguntas de autoevaluacion

• Por que 201 Created no equivale a 200 OK.
• Cuando tiene sentido PATCH frente a PUT.
• Que problema resuelve modelar recursos y no acciones arbitrarias.

Cierre

Una API madura empieza por respetar el protocolo que la sostiene; por eso HTTP y REST son la base de todo el curso.

Modulo 02. Contratos, recursos y versionado

Objetivo del modulo

Definir contratos estables entre proveedor y consumidor de API y aprender a evolucionarlos sin romper integraciones existentes.

Resultados esperados

• Explicar que es un contrato de API.
• Diseñar payloads y esquemas coherentes.
• Aplicar estrategias basicas de versionado.
• Entender compatibilidad hacia atras.

Desarrollo teorico

Un contrato de API es el acuerdo tecnico entre el servicio que expone capacidades y el consumidor que las utiliza. Incluye rutas, metodos, estructura de peticiones, respuestas, errores, headers, autenticacion y comportamiento esperado. Si el contrato cambia sin control, la integracion se rompe aunque el codigo del servicio "siga funcionando" para su propio equipo.

Versionar no significa añadir /v2/ por costumbre, sino planificar como evoluciona la interfaz. Cambios aditivos, como incorporar un campo opcional, suelen ser compatibles. En cambio, renombrar propiedades, cambiar tipos o eliminar valores puede romper clientes existentes. Por eso conviene distinguir cambios backward-compatible de breaking changes.

Especificacion OpenAPI

OpenAPI (antes Swagger) es el formato estandar para describir contratos de API REST. Define endpoints, parametros, esquemas de request/response y errores de forma legible por humanos y maquinas:

# openapi.yaml (fragmento)
openapi: "3.0.3"
info:
  title: API de Tickets
  version: "1.0.0"
paths:
  /tickets:
    get:
      summary: Listar tickets
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [open, in_progress, resolved, closed]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: Lista de tickets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Ticket"
                  total:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      summary: Crear ticket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTicketInput"
      responses:
        "201":
          description: Ticket creado
        "422":
          $ref: "#/components/responses/ValidationError"

components:
  schemas:
    Ticket:
      type: object
      required: [id, title, status, priority, createdAt]
      properties:
        id:
          type: string
          example: "TK-1042"
        title:
          type: string
        status:
          type: string
          enum: [open, in_progress, resolved, closed]
        priority:
          type: string
          enum: [low, medium, high, critical]
        assignee:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time

    CreateTicketInput:
      type: object
      required: [title, priority]
      properties:
        title:
          type: string
          minLength: 5
          maxLength: 300
        description:
          type: string
        priority:
          type: string
          enum: [low, medium, high, critical]

Con esta especificacion, herramientas como Swagger UI generan documentacion interactiva, y generadores de codigo pueden crear clientes tipados automaticamente.

Cambios compatibles frente a breaking changes

Entender que cambios rompen clientes y cuales no es fundamental para evolucionar la API:

Cambios compatibles (backward-compatible):
  - Añadir un campo opcional a la respuesta
  - Añadir un nuevo endpoint
  - Añadir un parametro de query opcional
  - Ampliar un enum con un nuevo valor (con precaucion)

Breaking changes:
  - Renombrar un campo existente (title -> ticketTitle)
  - Cambiar el tipo de un campo (id: number -> id: string)
  - Eliminar un campo de la respuesta
  - Cambiar un campo de opcional a obligatorio
  - Modificar la semantica de un codigo de estado

Estrategias de versionado

Las tres estrategias principales para versionar APIs tienen trade-offs distintos:

# 1. Version en la URL (la mas comun)
GET /api/v1/tickets
GET /api/v2/tickets

# 2. Version en cabecera
GET /api/tickets
Accept: application/vnd.myapp.v2+json

# 3. Version en parametro de query
GET /api/tickets?version=2

La version en URL es la mas visible y facil de implementar. La version en cabecera es mas "RESTful" pero menos practica para debugging y documentacion. En la mayoria de APIs publicas o internas, la version en URL es la eleccion mas pragmatica.

Deprecacion y comunicacion

Cuando una version o endpoint debe retirarse, la deprecacion necesita plazos claros y mecanismos de aviso:

// Middleware de deprecacion
function deprecationWarning(message: string, sunsetDate: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    res.setHeader('Deprecation', 'true');
    res.setHeader('Sunset', sunsetDate);
    res.setHeader('Link', '</api/v2/tickets>; rel="successor-version"');
    console.warn(`[DEPRECATED] ${req.method} ${req.path} - ${message}`);
    next();
  };
}

// Uso en rutas v1
router.get('/api/v1/tickets',
  deprecationWarning('Usa /api/v2/tickets', '2026-09-01T00:00:00Z'),
  ticketHandler,
);

Las cabeceras Deprecation y Sunset son estandares que los consumidores pueden detectar automaticamente. La cabecera Link con rel="successor-version" indica donde esta la nueva version.

Contenido ampliado

• OpenAPI como formato de descripcion.
• Versionado en URL, cabecera o media type.
• Estrategias de deprecacion y comunicacion.

Puntos clave

• Un contrato bien definido reduce malentendidos y retrabajo.
• No todo cambio exige nueva version, pero hay que evaluar compatibilidad.
• Documentar solo despues de implementar no basta; el contrato debe formar parte del diseño.
• La deprecacion necesita plazos y comunicacion.

Checklist operativa

• Describir requests, responses y errores de forma explicita.
• Marcar campos obligatorios y opcionales con claridad.
• Revisar si un cambio rompe consumidores existentes.
• Publicar ejemplos realistas de payloads.

Errores frecuentes

• Cambiar nombres o tipos sin control de version.
• Documentar respuestas parciales o inconsistentes.
• Considerar versionado solo cuando ya hay una crisis de integracion.
• No planificar deprecaciones.

Practica sugerida

Especifica un contrato OpenAPI simplificado para una API de usuarios y analiza que cambios serian compatibles o incompatibles con clientes existentes.

Preguntas de autoevaluacion

• Que define realmente un contrato de API.
• Cuando un cambio obliga a nueva version.
• Por que un campo opcional no impacta igual que uno renombrado.

Cierre

El contrato es el lenguaje compartido entre sistemas; cuidarlo es cuidar la integracion completa.