7 min lectura • Guide 803 of 877
Desarrollo API-First
El desarrollo API-first comienza con el contrato. GitScrum ayuda a los equipos a coordinar el diseño de API y rastrear la implementación contra especificaciones acordadas.
Enfoque API-First
Diseñar Antes de Construir
FLUJO DE TRABAJO API-FIRST:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TRADICIONAL (CODE-FIRST): │
│ ───────────────────────── │
│ │
│ Backend construye → Frontend espera → Integración → Retrabajo│
│ │ │ │
│ └─ Forma de API desconocida ───────┘ │
│ │
│ PROBLEMA: Frontend bloqueado, problemas de integración tarde│
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ API-FIRST: │
│ ────────── │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Diseñar │──→│ Contrato │──→│ Trabajo │──→│ Integrar │ │
│ │ API │ │ Acordado │ │ Paralelo │ │ y Test │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ ┌────┴────┐ │
│ │ │ │ │
│ │ Frontend Backend │
│ │ (con mock) (real) │
│ │ │ │ │
│ │ └────┬────┘ │
│ │ │ │
│ └──────────────┘ │
│ Mismo contrato │
│ │
│ BENEFICIO: Ambos equipos trabajan en paralelo │
└─────────────────────────────────────────────────────────────┘
Proceso de Diseño de API
FLUJO DE DISEÑO DE API:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PASO 1: IDENTIFICAR CONSUMIDORES │
│ ───────────────────────────────── │
│ • ¿Quién usará esta API? │
│ • ¿Frontend web, app móvil, terceros? │
│ • ¿Qué necesitan? │
│ │
│ PASO 2: DISEÑAR ENDPOINTS │
│ ───────────────────────── │
│ • Recursos y operaciones │
│ • Formas de request/response │
│ • Formatos de error │
│ • Autenticación │
│ │
│ PASO 3: DOCUMENTAR EN SPEC │
│ ─────────────────────────── │
│ • OpenAPI para REST │
│ • GraphQL SDL │
│ • Formato legible por máquina │
│ │
│ PASO 4: REVISAR CON CONSUMIDORES │
│ ───────────────────────────────── │
│ • Compartir spec con frontend/consumidores │
│ • Recopilar feedback │
│ • Iterar en diseño │
│ │
│ PASO 5: FINALIZAR CONTRATO │
│ ─────────────────────────── │
│ • Spec acordado se convierte en fuente de verdad │
│ • Generar servidor mock │
│ • Ambos equipos comienzan trabajo │
└─────────────────────────────────────────────────────────────┘
Especificación OpenAPI
Definición de Contrato
EJEMPLO DE SPEC OPENAPI:
┌─────────────────────────────────────────────────────────────┐
│ │
│ openapi: 3.0.0 │
│ info: │
│ title: Orders API │
│ version: 1.0.0 │
│ description: API para gestión de pedidos │
│ │
│ paths: │
│ /orders: │
│ post: │
│ summary: Crear nuevo pedido │
│ requestBody: │
│ content: │
│ application/json: │
│ schema: │
│ $ref: '#/components/schemas/CreateOrder' │
│ responses: │
│ '201': │
│ description: Pedido creado │
│ content: │
│ application/json: │
│ schema: │
│ $ref: '#/components/schemas/Order' │
│ │
│ components: │
│ schemas: │
│ Order: │
│ type: object │
│ properties: │
│ id: │
│ type: string │
│ status: │
│ type: string │
│ enum: [pending, confirmed, shipped] │
│ items: │
│ type: array │
│ items: │
│ $ref: '#/components/schemas/OrderItem' │
│ │
│ BENEFICIOS: │
│ ──────────── │
│ ✓ Documentación auto-generada │
│ ✓ Mock server automático │
│ ✓ Validación de request/response │
│ ✓ Generación de código cliente │
│ ✓ Tests de contrato │
└─────────────────────────────────────────────────────────────┘
Mock Servers
Desarrollo con Mocks
FLUJO CON MOCK SERVER:
┌─────────────────────────────────────────────────────────────┐
│ │
│ SETUP: │
│ ─────── │
│ 1. Crear spec OpenAPI │
│ 2. Generar mock server (Prism, Stoplight, etc.) │
│ 3. Frontend desarrolla contra mock │
│ 4. Backend implementa API real │
│ 5. Cuando backend listo, cambiar URL │
│ │
│ DIAGRAMA: │
│ ───────── │
│ │
│ ┌──────────────┐ │
│ │ OpenAPI │ │
│ │ Spec │ │
│ └──────┬───────┘ │
│ │ │
│ ┌───┴───┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────┐ ┌──────┐ │
│ │ Mock │ │ Real │ │
│ │Server│ │ API │ │
│ └──┬───┘ └──┬───┘ │
│ │ │ │
│ │ Dev │ Prod │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────┐ │
│ │ Frontend │ │
│ └────────────────┘ │
│ │
│ HERRAMIENTAS: │
│ ───────────── │
│ • Prism (de Stoplight) - Mock desde OpenAPI │
│ • json-server - Mock rápido desde JSON │
│ • Mirage JS - Mock en el navegador │
│ • WireMock - Mock para Java │
│ • MockServer - Mock configurable │
└─────────────────────────────────────────────────────────────┘
Contract Testing
Validación de Contrato
CONTRACT TESTING:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ¿QUÉ ES? │
│ ───────── │
│ Verificar que productor y consumidor cumplen el contrato. │
│ │
│ TIPOS: │
│ ─────── │
│ │
│ CONSUMER-DRIVEN CONTRACTS: │
│ ─────────────────────────── │
│ • Consumidor define lo que necesita │
│ • Productor verifica que cumple │
│ • Herramientas: Pact, Spring Cloud Contract │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Consumer │───→│ Contract │ │
│ │ (Frontend) │ │ (Pact file) │ │
│ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Producer │ │
│ │ Verifica │ │
│ │ contra Pact │ │
│ └─────────────┘ │
│ │
│ SCHEMA VALIDATION: │
│ ────────────────── │
│ • Validar que API cumple OpenAPI spec │
│ • En CI/CD como check automático │
│ • Herramientas: Spectral, OpenAPI CLI │
│ │
│ BENEFICIOS: │
│ ─────────── │
│ ✓ Detectar breaking changes antes de deploy │
│ ✓ Confianza en integración │
│ ✓ Documentación siempre actualizada │
│ ✓ Comunicación clara entre equipos │
└─────────────────────────────────────────────────────────────┘
Planificación en GitScrum
Tareas de API-First
ORGANIZACIÓN EN GITSCRUM:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ÉPICA: Orders API │
│ ───────────────── │
│ │
│ FASE 1: DISEÑO (Sprint 1) │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ API-001: Identificar consumidores y casos de uso ││
│ │ API-002: Diseñar endpoints y schemas ││
│ │ API-003: Escribir OpenAPI spec ││
│ │ API-004: Review con frontend ││
│ │ API-005: Finalizar contrato ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ FASE 2: IMPLEMENTACIÓN PARALELA (Sprint 2-3) │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ BACKEND: ││
│ │ API-010: Implementar POST /orders ││
│ │ API-011: Implementar GET /orders/{id} ││
│ │ API-012: Implementar GET /orders ││
│ │ API-013: Tests y documentación ││
│ │ ││
│ │ FRONTEND (con mock): ││
│ │ FE-020: UI de crear pedido ││
│ │ FE-021: Vista de detalle de pedido ││
│ │ FE-022: Lista de pedidos ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ FASE 3: INTEGRACIÓN (Sprint 4) │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ INT-030: Cambiar frontend de mock a API real ││
│ │ INT-031: Tests E2E ││
│ │ INT-032: Ajustes de integración ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ Labels: [api-first] [orders-api] [v1] │
└─────────────────────────────────────────────────────────────┘