GuíaBásico
Guía de Diseño de APIs e Integración
Aprende a diseñar el contrato por el que un sistema habla con otros: modelar recursos, elegir los verbos y códigos de estado correctos, diseñar peticiones y respuestas (paginación, filtrado, errores), y —el eje de la guía— versionar y evolucionar una API sin romper a quien ya la consume. Todo se trabaja sobre un solo caso de principio a fin: la API pública de Catalog y Orders de Mercado, un marketplace con endpoints reales (`GET /v1/products`, `POST /v1/orders`) que se construyen y prueban en Python. Vas a diseñar paginación por cursor ejecutada de verdad, idempotencia con `Idempotency-Key`, un contrato de errores en formato `problem+json` (RFC 9457), validación contra JSON Schema, y demostrar con un test cómo un cambio aditivo no rompe a un consumidor viejo mientras uno destructivo sí. Cierra con el criterio para saber cuándo REST no es la respuesta y conviene gRPC o GraphQL.
- 64
- lecciones
- 8
- módulos
- Inglés · Español
- disponible en
- Sí
- certificado
- Gratis
- acceso
Resultados
Lo que vas a poder hacer
- Entender una API como un contrato que otros construyen encima, y modelar recursos (sustantivos) en vez de acciones
- Aplicar REST correctamente: verbos HTTP y su semántica (idempotente/seguro), y los códigos de estado adecuados para cada caso
- Diseñar peticiones y respuestas: paginación por cursor (y por qué es mejor que offset), filtrado, ordenamiento y formatos de fecha/dinero
- Construir un contrato de errores accionable en `problem+json` (RFC 9457) y hacer `POST` idempotente con `Idempotency-Key`
- Versionar y evolucionar una API sin romper a los consumidores: distinguir cambios aditivos de destructivos, y aplicar el patrón tolerant reader
- Formalizar el contrato con OpenAPI y JSON Schema, y validar requests/responses contra el schema
- Decidir con criterio cuándo REST no alcanza y conviene gRPC (contrato fuerte, streaming) o GraphQL (el cliente pide justo lo que necesita)
- Diseñar de punta a punta la API de Catalog y Orders de Mercado: contrato, schema, idempotencia y un plan de versionado con un cambio evolutivo demostrado
Antes de empezar
Qué necesitas traer
Es para ti si...
- Backend devs que diseñan APIs HTTP y quieren dejar de improvisar contratos que se rompen al primer cambio
- Devs que ya construyeron endpoints REST pero nunca versionaron una API en producción con consumidores reales
- Equipos evaluando si REST alcanza o conviene migrar partes de su API a gRPC o GraphQL
- Cualquiera que necesite diseñar paginación, errores e idempotencia con criterio, no por copiar y pegar de otro proyecto
Requisitos y materiales
- Python básico e HTTP básico (verbos, códigos de estado, JSON)
- Haber construido al menos un endpoint o servicio backend, aunque sea simple
- No se requiere experiencia previa con OpenAPI, gRPC ni GraphQL
Contenido
El temario, módulo por módulo
Abre cualquiera para ver sus lecciones.
- 1. Presentación del módulo: la API de Mercado como un contrato público
- 2. Una API es un contrato
- 3. Orientada al consumidor, no a la tabla de la BD
- 4. Recursos, no acciones
- 5. Consistencia y el principio de la menor sorpresa
- 6. El costo de romper el contrato
- 7. La API de Mercado: buenos y malos ejemplos
- 8. Mini-proyecto: rediseña un endpoint que filtra el esquema
- 1. Presentación del módulo: diseñar lo que entra y lo que sale
- 2. Paginación: por qué cursor gana a offset
- 3. Filtrado y ordenamiento
- 4. Selección de campos: sparse fieldsets
- 5. Envelopes vs recurso pelón
- 6. Fechas y horas: ISO 8601 en UTC
- 7. Dinero: centavos enteros, nunca float
- 8. Proyecto: diseña las respuestas de `GET /products` de Mercado
- 1. Presentación del módulo: el error es parte del contrato
- 2. Por qué un contrato de errores
- 3. `problem+json`: el formato estándar (RFC 9457)
- 4. 400 vs 422 vs 409: qué código para qué falla
- 5. Los otros códigos: 401, 403, 404, 410, 429
- 6. Errores accionables: qué campo y cómo arreglarlo
- 7. Idempotencia de POST con Idempotency-Key
- 8. Proyecto: el contrato de errores de Mercado
- 1. Presentación del módulo: la promesa que ya no puedes romper
- 2. Por qué evolucionar rompe
- 3. Cambios aditivos vs destructivos
- 4. Versionar en la URL vs en un header
- 5. El tolerant reader
- 6. Deprecación con Sunset
- 7. ¿Este cambio rompe? La checklist
- 8. Proyecto: evoluciona el Product de Mercado sin romper al consumidor viejo
- 1. Presentación del módulo: el contrato que se puede leer sin ti
- 2. Por qué un contrato explícito
- 3. OpenAPI: describir la API en un archivo
- 4. JSON Schema: la forma del dato
- 5. Contract-first: el contrato antes que el código
- 6. Validar el request contra el schema
- 7. La documentación como parte del contrato
- 8. Proyecto: el OpenAPI + JSON Schema de un endpoint de Mercado
- 1. Presentación del módulo: cuando el default deja de ser gratis
- 2. Cuando REST no alcanza
- 3. gRPC y protobuf: el contrato que genera código
- 4. Cuándo elegir gRPC
- 5. GraphQL y el pedido exacto
- 6. El problema N+1 de GraphQL
- 7. La matriz de elección: REST, gRPC, GraphQL
- 8. Proyecto: elige el protocolo para cada límite de Mercado
- 1. Presentación del módulo: la API como contrato, en un solo diseño
- 2. Recursos y endpoints: la superficie completa
- 3. Paginación por cursor y filtrado
- 4. El contrato de errores y la idempotencia
- 5. El JSON Schema y la doc como contrato
- 6. El plan de versionado y un cambio que no rompe
- 7. La decisión de protocolo por límite
- 8. Proyecto: diseña y ejecuta la API de Catalog+Orders
Dudas frecuentes
Lo que suele preguntarse
Sin límite. Es una guía gratuita: entras cuando quieras, las veces que quieras.
No. Los módulos están ordenados de menos a más, pero puedes saltar al que necesites. Tu progreso se guarda por lección.
Lo que haga falta está en «Qué necesitas traer», arriba. Si no aparece nada ahí, puedes empezar desde cero.
En el grupo de WhatsApp del Club, y cada quince días hay un live con un instructor donde se resuelven dudas en vivo.
Sí. Al terminar todas las lecciones se emite automáticamente, con un código verificable que puedes compartir en LinkedIn.
Empieza cuando quieras
Lo que dicen los estudiantes
Estas reseñas son de estudiantes inscritos que completaron al menos el 50% del curso. Moderamos las reseñas solo por motivos de contenido (spam, lenguaje ofensivo, datos personales), nunca por ser críticas o negativas.
Aún no hay reseñas aprobadas.
¡Sé el primero en compartir tu experiencia!