Designing the API

The API is the contract between your system and its clients. In a design, it also does something more useful: it is a checklist. Every endpoint must be served by the high-level design you draw next.

One endpoint per requirement

Go through your functional requirements and write the call that satisfies each one. For the URL shortener:

1 POST /links
2 { "url": "https://example.com/a/very/long/path", "alias": "launch", "expiresAt": "2027-01-01" }
3 → 201 { "code": "launch", "shortUrl": "https://sho.rt/launch" }
4 
5 GET /{code}
6 → 302 Location: https://example.com/a/very/long/path

That is the whole API. Two endpoints, two requirements.

REST conventions that keep you out of trouble

• Resources are nouns, methods are verbs. POST /links, GET /links/{code}, DELETE /links/{code}. Not POST /createLink.
• Plural collections. /events/{id}/seats, not /event/{id}/seat.
• Correct status codes. 201 Created, 302 Found for redirects, 404 for an unknown code, 409 Conflict when a custom alias is taken, 429 when rate limited.
• Paginate collections. GET /feed?cursor=abc&limit=20. A cursor (an opaque pointer to the last item seen) stays correct when new items arrive at the top, unlike ?page=3.

REST, RPC or real time?

REST over HTTP is the default for public APIs. Two alternatives come up often:

A chat system, for example, typically uses REST for history (GET /chats/{id}/messages?cursor=…) and a WebSocket for live messages.

Keep it high level

In a design discussion, the API does not need every field and header. You need:

• the method and path (or the message type for real-time APIs),
• the important inputs,
• the important outputs,
• anything that affects the design: pagination, idempotency keys, rate limits.

1 POST /payments
2 Idempotency-Key: 7f3c…   ← lets the client retry safely without double-charging
3 { "orderId": "o_123", "amount": 4999, "currency": "INR" }

That idempotency key is exactly the kind of detail worth including: it changes the design, because the server now needs to remember which keys it has already processed.