Lesson 1 of 2

APIs & Integration Design

Designing the API a partner will integrate against means making a handful of choices correctly before anyone else's code depends on them.

Designing a resource-oriented API

Model the nouns in your system, and let HTTP methods express the verbs.

A resource-oriented API represents each thing in your system — a user, an order, a subscription — as an addressable path, and relies on the HTTP method (GET, POST, PUT, DELETE) to express the action, rather than encoding a verb into the path itself. This keeps the API predictable: once you know the shape of one resource, you can guess the shape of the next one correctly.

Choices that age well

Four decisions are much cheaper to make correctly upfront than to retrofit later.

Versioning strategy

Decide once, upfront, how you'll evolve the API without breaking existing clients — a URL prefix (/v1/), a header, or a date-based version. Retrofitting this after clients exist is far more painful.

Pagination

Any endpoint that can return an unbounded list needs pagination from day one — cursor-based scales better than offset-based once the underlying data changes while paging.

Idempotency keys

Let a client safely retry a write without risking a duplicate — the server recognizes a repeated key and returns the original result instead of creating a second one.

Consistent error shape

Every error response should have the same predictable shape — a stable code, a human message — so client code can handle errors generically instead of per-endpoint.

Exercises

Look at the sanitized before/after design review below, then work through both exercises.

Before: GET /getUserData?id=123
  - verb in the path, not a resource
  - no pagination on the nested "orders" array
  - errors return plain text, not JSON

After: GET /v1/users/123
  - resource-oriented, versioned
  - GET /v1/users/123/orders?cursor=... for the list
  - errors: { "error": { "code": "not_found", "message": "..." } }

Concept check

Answer in your head first, then click a question to reveal the answer.

Scenario checklist

Work through the sample design review and check each item off. Progress is saved in your browser.

Identify what is wrong with the "before" endpoint designIdentify which specific change fixes each problemDetermine what pagination strategy the "after" version should use, and whyConfirm the error response shape is consistent across endpointsDescribe one more design choice you would want locked in before this API ships

Go deeper

These primers are a starting point. Read the primary sources to build real fluency.

Google Cloud: Resource-oriented designThe design philosophy behind treating an API as nouns, not verbs Stripe API Reference: VersioningA widely-cited real-world versioning strategy that ships breaking changes safely Stripe Docs: Idempotent requestsThe mechanism this lesson's idempotency-key exercise is built on

Training Notes

What building this project taught me.

This is the build-it counterpart to Support's debug-it lesson

TSE Onboarding's "API Debugging in the Field" covers reproducing a customer bug in Postman. This lesson is the same underlying skills — REST fundamentals, idempotency, errors — from the design side, before an API ships.

These four choices are hard to retrofit, which is why they're grouped

Versioning, pagination, idempotency, and error shape all share one property: adding them after clients already exist is a breaking change. Getting them right on day one avoids that entirely.