The Complete Guide to REST API¶

REST is the de-facto standard for web APIs. Here is how to design it properly.

REST Principles¶

• Stateless — the server does not hold session state
• Resource-based — URLs represent resources
• HTTP methods for operations
• Standard status codes

CRUD Mapping¶

GET /users -> list GET /users/123 -> detail POST /users -> create PUT /users/123 -> full update PATCH /users/123 -> partial update DELETE /users/123 -> delete

Response Format¶

// Success { “data”: { “id”: 123, “name”: “Jan” } }

// Error { “error”: { “code”: “NOT_FOUND”, “message”: “User not found” } }

// List { “data”: […], “pagination”: { “total”: 100, “page”: 1, “limit”: 20 } }

Authentication¶

• API Key — simple, for server-to-server
• Bearer Token (JWT) — standard for SPA/mobile
• OAuth 2.0 — for third-party access
• Session cookie — for traditional web apps

Versioning¶

URL path (recommended)¶

GET /v1/users GET /v2/users

Header¶

Accept: application/vnd.myapi.v1+json

Rate Limiting¶

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1707900000

Pagination¶

Offset¶

GET /users?page=2&limit=20

Cursor (better for large datasets)¶

GET /users?cursor=abc123&limit=20

Golden Rule¶

An API should be intuitive. If you need documentation to understand the URL, redesign it.