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.
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.
-
Describe the domain. Say what the API needs to expose. Ask for the core resources, how they relate, and the operations clients need.
-
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.
-
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.
-
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.