What is REST?
Representational State Transfer
REST is an architectural style that uses standard HTTP methods to perform CRUD operations on resources. It emphasizes stateless communication and uniform interfaces between clients and servers.
- Stateless
- Client-server separation
- Cacheable
- Layered architecture
- Code on demand (optional)
Why REST?
Provides a simple, uniform interface that works with standard HTTP protocols. Enables decoupled development between client applications and server infrastructure.
REST Principles
Statelessness
The server must not store any client state between requests. All needed information should be included in each request.
Client-Server
Clean separation of concerns between client and server allows independent development and scaling of components.
Cacheable
Responses must define themselves as cacheable or non-cacheable to improve network efficiency through caching.
HTTP Methods
Retrieve representation
GET /api/users/123
Create resource
POST /api/users
Replace entire resource
PUT /api/users/123
Remove resource
DELETE /api/users/123
RESTful URL Design
Key Principles
-
Use plural nouns for resources (e.g.,
/api/books) - Avoid verbs in URLs, use HTTP methods instead
-
Nested resources for relations (e.g.,
/api/books/123/comments) -
Use standard query parameters for filtering (e.g.,
/api/books?author=tolkien)
Example API Routes
GET /api/books → All books
GET /api/books/123 → Book by ID
POST /api/books → Create new book
PUT /api/books/123 → Update book
DELETE /api/books/123 → Delete book
Query Parameters
/api/users?sort=name - Sort results
/api/books?author=asimov&year=1950 - Filter results
/api/books?limit=10&page=2 - Pagination
Important HTTP Status Codes
200 OK
Standard success response for GET, PUT, POST requests when operation succeeds.
201 Created
Resource created successfully (common after POST).
204 No Content
Used for DELETE requests that succeed but return no content.
400 Bad Request
Invalid client input that the server cannot process.
401 Unauthorized
Authentication credentials missing or invalid.
404 Not Found
Resource identified by request URI does not exist.
500 Internal Server Error
Generic error message when the server fails to fulfill valid request.
503 Service Unavailable
Server temporarily unavailable (maintenance, overload).
Best Practices
Versioning
- URI versioning:
/api/v1/books - Header versioning:
Accept: application/vnd.myapp.v2+json
Content Negotiation
Support multiple representations:
GET /api/books/123
Accept: application/json → Returns JSON
Accept: application/xml → Returns XML
Pagination
GET /api/books?page=2&limit=20
Response should include:
Link:; rel="next", ; rel="prev" X-Total-Count: 125(total items)
Key Takeaways
- Use HTTP methods as defined in the specification (GET, POST, PUT, DELETE)
- Design resources to reflect your domain model using meaningful URLs
- Leverage HTTP headers for conditional requests and caching (If-Match, ETag)
- Use appropriate HTTP status codes to communicate API state
- Design APIs with scalability and performance in mind from the start