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:                              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

┌─────────────────────────────────────────────────────┐
│           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 requests):              GraphQL (single request):

GET /users/123                         query {
GET /users/123/orders                    user(id: "123") {
GET /orders/456/items                      name
                                           email
(3 round trips,                            orders {
 over-fetching)                              id
                                             items {
                                               name
                                               price
                                             }
                                           }
                                         }
                                       }
                                       (1 round trip, exact data)

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

When an endpoint returns a large collection, pagination is essential.

Cursor-Based vs Offset-Based