GuideBeginner
Api Design And Integration
Learn to design the contract that lets one system talk to others: model resources, choose the right verbs and status codes, design requests and responses (pagination, filtering, errors), and — the core of this guide — version and evolve an API without breaking the clients that already depend on it. Everything is built on a single case study from start to finish: the public Catalog and Orders API of Mercado, a marketplace with real endpoints (`GET /v1/products`, `POST /v1/orders`) that get built and tested in Python. You'll design cursor-based pagination that actually runs, idempotency with `Idempotency-Key`, an error contract in `problem+json` format (RFC 9457), JSON Schema validation, and prove with a test how an additive change doesn't break an old consumer while a breaking change does. The guide closes with the judgment to know when REST isn't the answer and gRPC or GraphQL fit better.
- 64
- lessons
- 8
- modules
- English · Spanish
- available in
- Yes
- certificate
- Free
- access
Outcomes
What you'll be able to do
- Understand an API as a contract others build on top of, and model resources (nouns) instead of actions
- Apply REST correctly: HTTP verbs and their semantics (idempotent/safe), and the right status codes for each case
- Design requests and responses: cursor-based pagination (and why it beats offset), filtering, sorting, and date/money formats
- Build an actionable error contract in `problem+json` (RFC 9457) and make `POST` idempotent with `Idempotency-Key`
- Version and evolve an API without breaking consumers: distinguish additive changes from breaking ones, and apply the tolerant reader pattern
- Formalize the contract with OpenAPI and JSON Schema, and validate requests/responses against the schema
- Judge when REST isn't enough and gRPC (strong contract, streaming) or GraphQL (clients fetch exactly what they need) fit better
- Design Mercado's Catalog and Orders API end to end: contract, schema, idempotency, and a versioning plan with a proven evolutionary change
Before you start
What you need to bring
It's for you if...
- Backend devs designing HTTP APIs who want to stop improvising contracts that break on the first change
- Devs who've built REST endpoints before but never versioned a production API with real consumers
- Teams evaluating whether REST is enough or parts of their API should move to gRPC or GraphQL
- Anyone who needs to design pagination, errors, and idempotency with judgment instead of copy-pasting from another project
Requirements and materials
- Basic Python and basic HTTP (verbs, status codes, JSON)
- Having built at least one backend endpoint or service, even a simple one
- No prior experience with OpenAPI, gRPC, or GraphQL required
Content
The syllabus, module by module
Open any of them to see its lessons.
- 1. Module introduction: Mercado's API as a public contract
- 2. An API is a contract
- 3. Consumer-oriented, not the DB table
- 4. Resources, not actions
- 5. Consistency and the principle of least surprise
- 6. The cost of breaking the contract
- 7. The Mercado API: good and bad examples
- 8. Mini-project: redesign an endpoint that leaks the schema
- 1. Module introduction: designing what comes in and what goes out
- 2. Pagination: why cursor beats offset
- 3. Filtering and sorting
- 4. Field selection: sparse fieldsets
- 5. Envelopes vs bare resource
- 6. Dates and times: ISO 8601 in UTC
- 7. Money: integer cents, never float
- 8. Project: design Mercado's `GET /products` responses
- 1. Module introduction: the error is part of the contract
- 2. Why an error contract
- 3. `problem+json`: the standard format (RFC 9457)
- 4. 400 vs 422 vs 409: which code for which failure
- 5. The other codes: 401, 403, 404, 410, 429
- 6. Actionable errors: which field and how to fix it
- 7. Idempotency of POST with Idempotency-Key
- 8. Project: Mercado's error contract
- 1. Module introduction: the promise you can no longer break
- 2. Why evolving breaks
- 3. Additive vs destructive changes
- 4. Versioning in the URL vs in a header
- 5. The tolerant reader
- 6. Deprecation with Sunset
- 7. Does this change break? The checklist
- 8. Project: evolve Mercado's Product without breaking the old consumer
- 1. Module introduction: the contract that can be read without you
- 2. Why an explicit contract
- 3. OpenAPI: describing the API in a file
- 4. JSON Schema: the shape of data
- 5. Contract-first: the contract before the code
- 6. Validating the request against the schema
- 7. Documentation as part of the contract
- 8. Project: the OpenAPI + JSON Schema of a Mercado endpoint
- 1. Module introduction: when the default stops being free
- 2. When REST isn't enough
- 3. gRPC and protobuf: the contract that generates code
- 4. When to choose gRPC
- 5. GraphQL and the exact request
- 6. GraphQL's N+1 problem
- 7. The choice matrix: REST, gRPC, GraphQL
- 8. Project: choose the protocol for each Mercado boundary
- 1. Module introduction: the API as a contract, in a single design
- 2. Resources and endpoints: the complete surface
- 3. Cursor pagination and filtering
- 4. The error contract and idempotency
- 5. The JSON Schema and the docs as contract
- 6. The versioning plan and a change that doesn't break
- 7. The protocol decision per boundary
- 8. Project: design and execute the Catalog+Orders API
Common questions
What people usually ask
No limit. It's a free guide: come in whenever you like, as often as you like.
No. Modules run from easier to harder, but you can jump to the one you need. Progress is saved per lesson.
Whatever is needed is listed under “What you need to bring”, above. If nothing is listed there, you can start from zero.
In the Club's WhatsApp group, and every two weeks there's a live with an instructor where questions get worked through.
Yes. It's issued automatically once you finish every lesson, with a verifiable code you can share on LinkedIn.
Start whenever you like
What students say
These reviews are from enrolled students who completed at least 50% of the course. We moderate reviews only on content grounds (spam, offensive language, personal data), never for being critical or negative.
No approved reviews yet.
Be the first to share your experience!