API Design

~25 min · Foundations · Alex Xu Vol 1 · ByteByteGo

Ref

Primary Source

ByteByteGo — "REST vs GraphQL vs gRPC" · API Design Best Practices

ByteByteGo's visual breakdowns of API styles are excellent. Supplement with the REST API Design guide at restfulapi.net.

API as a Contract

An API is a contract between services. In system design interviews, defining the API is Step 3's first task: what can clients do, what do they send, what do they get back? A clear API prevents scope creep and grounds your architecture.

REST vs GraphQL vs gRPC

The three API paradigms — each optimized for a different use case

API Style	Best For	Avoid When
REST	Public APIs, browser clients, CRUD operations	Need extreme performance or streaming
GraphQL	Mobile clients with limited bandwidth, complex nested data	Simple CRUD, backend-to-backend
gRPC	Internal microservice communication, streaming, low latency	Public APIs, browser clients without proxy

💡 Interview default

Default to REST for external APIs, gRPC for internal service-to-service communication. Say "I'll use REST for the client-facing API since it's universally supported, and gRPC for internal service communication for the performance benefit."

RESTful API Design Principles

In interviews, you'll usually sketch 2–4 REST endpoints. Know these conventions cold:

Verb	Meaning	Idempotent?
`GET`	Read — no side effects	Yes
`POST`	Create — always creates new resource	No
`PUT`	Replace entire resource	Yes
`PATCH`	Update specific fields	No (usually)
`DELETE`	Remove resource	Yes

URL Design

Patterns

GET /users/{user_id} → get user
GET /users/{user_id}/posts → user's posts
POST /users/{user_id}/posts → create post
DELETE /posts/{post_id} → delete post
GET /feed?limit=20&cursor=xyz → paginated feed

Pagination

Never return all records at once. Two main patterns:

Offset-based (Page numbers)

GET /posts?page=3&limit=20
→ skip 60, take 20

Simple to implement.
Problem: if items are added/deleted
during pagination, pages shift —
items are skipped or duplicated.

Cursor-based (Preferred)

GET /posts?after=post_id_abc&limit=20
→ posts after this cursor

Stable: items added/deleted don't
shift the cursor position.
Standard for social feeds, timelines.
Used by Twitter, Instagram, GitHub.

Idempotency

An operation is idempotent if performing it multiple times produces the same result as once. Critical for distributed systems where retries are common.

Problem: Payment retry creates duplicate charge

POST /payments { amount: 100 }
→ Network times out, client retries
→ POST /payments { amount: 100 } again
→ Two charges of $100!

Solution: Idempotency key

POST /payments
Idempotency-Key: uuid-123-abc
{ amount: 100 }
→ Server stores result for this key
→ Retry with same key → same response
→ No double charge!

Rate Limiting

APIs must be protected from abuse. Rate limiting allows N requests per time window per client (by API key, user ID, or IP). Responses:

429 Too Many Requests — standard rate limit exceeded response
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Deep dive: Lesson 16 — Rate Limiting

Versioning

APIs change over time. Breaking changes require versioning so old clients aren't broken:

URL versioning: /v1/users → /v2/users — explicit, easy to route
Header versioning: Accept: application/vnd.api+json; version=2
Query param: /users?version=2

URL versioning is the most common in practice. Deprecate old versions gracefully — give clients 6–12 months notice.

Check Your Understanding

1. You're building internal service-to-service communication between a user service and an order service. Which API style gives you the best performance?

2. You're building an infinite-scroll news feed. Which pagination style prevents items from being skipped when new posts are added at the top?

3. A client charges a card, the network times out before receiving the response, and retries the request. What prevents a duplicate charge?

🎓 API design comes up in every interview's high-level design phase. Ask me to sketch the API for any specific system — Twitter's feed, a URL shortener, a payment service — and I'll walk through the full design.