API Design

APIs are the contracts between services. A well-designed API is intuitive, consistent, and resilient. This lesson covers REST, GraphQL, gRPC, versioning, pagination, rate limiting, idempotency, API gateways, and documentation.

---

REST Principles

REST (Representational State Transfer) is the most common API architectural style.

Core Principles

Principle	Description
Stateless	Each request contains all information needed
Resource-based	URLs represent resources, not actions
HTTP methods	Use GET, POST, PUT, PATCH, DELETE semantically
Uniform interface	Consistent URL patterns and response formats

RESTful URL Design

Good (RESTful)	Bad
GET /users	GET /getUsers
GET /users/123	GET /getUserById?id=123
POST /users	POST /createUser
PUT /users/123	POST /updateUser
DELETE /users/123	POST /deleteUser?id=123
GET /users/123/orders	GET /getOrdersByUser?userId=123

HTTP Methods and Status Codes

Method	Purpose	Idempotent	Request Body	Common Responses
GET	Read resource	Yes	No	200, 404
POST	Create resource	No	Yes	201, 400
PUT	Replace resource	Yes	Yes	200, 404
PATCH	Partial update	No*	Yes	200, 404
DELETE	Remove resource	Yes	No	204, 404

Status	Common HTTP Status Codes
200	OK — Request succeeded
201	Created — Resource created
204	No Content — Successful with no body
400	Bad Request — Invalid input
401	Unauthorised — Authentication required
403	Forbidden — Not enough permissions
404	Not Found — Resource does not exist
409	Conflict — Resource state conflict
429	Too Many Requests — Rate limited
500	Internal Server Error
503	Service Unavailable — Temporarily down

---

GraphQL

GraphQL lets clients request exactly the data they need in a single request.

REST — multiple round trips	GraphQL — single round trip
GET /users/123 → GET /users/123/orders → GET /orders/456/items (3 requests; tends to over-fetch fields you do not need)	One query: user(id: "123") returning name, email and orders { id, items { name, price } } (1 request; returns exactly the fields requested)

REST vs GraphQL vs gRPC

Feature	REST	GraphQL	gRPC
Protocol	HTTP/1.1 or HTTP/2	HTTP (usually POST)	HTTP/2
Data format	JSON (typically)	JSON	Protocol Buffers
Schema	Optional (OpenAPI)	Required (SDL)	Required (.proto)
Over-fetching	Common	No	No
Under-fetching	Common	No	No
Streaming	Limited	Subscriptions	Bidirectional
Performance	Good	Good	Excellent
Learning curve	Low	Medium	Medium-High
Best for	Public APIs, CRUD	Complex nested data	Internal microservices

---

API Versioning

APIs evolve over time. Versioning prevents breaking changes from affecting existing clients.

Versioning Strategies

Strategy	Example	Pros	Cons
URL path	/v1/users, /v2/users	Explicit, easy to route	URL pollution
Query param	/users?version=2	Easy to add	Easy to forget
Header	Accept: application/vnd.api.v2	Clean URLs	Hidden, harder to test
Content type	Content-Type: application/v2+json	Precise	Complex

Tip: URL path versioning (/v1/, /v2/) is the most common and most developer-friendly approach.

---

Pagination