Technical

Settle API design decisions before you write code

Give each resource its own branch, compare design options side by side, and check the result against what each client needs.

See it in action

An existing API mapped node by node, from its core resources to its SDKs.

Open the full map

How it works

Describe your domain and the model proposes resources and operations. Each resource and each shared concern gets its own branch, and every question under it keeps that part of the API in context.

  1. Describe the domain. Say what the API needs to expose. Ask for the core resources, how they relate, and the operations clients need.

  2. Branch on each design decision. Under a resource, ask which fields to expose, how to handle sub-resources and which HTTP methods to support. A question like “Should order items be embedded or linked?” gets one branch per answer.

  3. Give shared concerns their own branches. Authentication, pagination, rate limiting and error handling apply to every endpoint. Decide each pattern once, on its own branch.

  4. Check against client needs. Walk through a client’s screens on the map. If the mobile app needs three calls to render one screen, branch into fixes such as GraphQL, compound documents or a backend for frontend.

Why a map instead of a design doc

A breaking change is expensive once an API is public. On a map, you can put two options side by side, such as /orders/{id}/items and /order-items?order_id={id}, and ask under each how it affects caching, authorization and client code.

Each consumer uses the API differently. Give the mobile app, the web dashboard and a third-party integration a branch each, and ask how each one uses the same resources.

Example

Say you are designing a billing API for a SaaS product. The map splits into Subscriptions, Invoices, Payment Methods and Usage Records. Under Subscriptions you compare proration, an immediate switch and an end-of-cycle switch for plan changes. A branch on usage-based billing shows it needs a metering endpoint that feeds invoice generation, so you design those two together. Further branches cover idempotency keys for payment retries and webhook events for async status updates.

Now try it yourself

Design a REST API for an e-commerce order management system
The API should center on four core resources: Orders, Products, Customers, and Payments. Use nested routes for sub-resources like order items and shipping addresses, and expose idempotent endpoints for payment processing.
How should we handle partial updates vs full replacements?
Use PATCH with JSON Merge Patch (RFC 7386) for partial updates and PUT for full replacements. PATCH is more bandwidth-efficient and reduces conflicts in concurrent editing scenarios, but requires careful validation of nullable fields.

Ready to try api design?