REST

Category: Development

What is REST?

REST (Representational State Transfer) is an architectural style for designing distributed systems, specifically web services. REST is not a protocol or standard, but a set of architectural constraints that ensure scalability, reliability, and performance.

Created by Roy Fielding in his doctoral dissertation in 2000, REST became the dominant approach for designing web APIs.

Main principles of REST:

  1. 1

    Client-Server Architecture

    Separating the client interface from the server's data storage. This allows independent development and improves portability.

  2. 2

    Stateless

    Every request from the client to the server must contain all the information needed to understand and process the request. The server does not store state between requests.

  3. 3

    Cacheable

    The responses must be implicitly or explicitly defined as cacheable or not. This improves performance.

  4. 4

    Uniform Interface

    A uniform interface between components that simplifies the architecture and separates implementations.

  5. 5

    Layered System

    The client cannot determine whether it is connected directly to the final server or to an intermediate layer.

  6. 6

    Code on Demand (optional)

    The server can temporarily extend the functionality of the client by transmitting executable code.

Key concepts in REST:

Resources

Everything that can be named is a resource - user, product, order. Resources are identified with URIs.

/api/users/123

Representations

Different formats of the resource - JSON, XML, HTML. The client and server agree on the format through Content-Type.

Content-Type: application/json

Uniform Interface

Standardized HTTP methods and response codes for all operations.

HTTP Methods in REST:

GET

Retrieval of a resource or collection of resources

  • Safe - does not change the state
  • Idempotent - multiple executions give the same result
  • Cacheable
GET /api/users

POST

Creation of a new resource

  • Not safe - changes the state
  • Not idempotent - creates a different resource every time
  • Usually not cached
POST /api/users

PUT

Full update of a resource

  • Not safe - changes the state
  • Idempotent - multiple executions give the same result
  • Usually not cached
PUT /api/users/123

PATCH

Partial update of a resource

  • Not safe - changes the state
  • Idempotent - with correct implementation
  • Usually not cached
PATCH /api/users/123

DELETE

Deletion of a resource

  • Not safe - changes the state
  • Idempotent - after the first deletion, the resource no longer exists
  • Usually not cached
DELETE /api/users/123

HTTP Status Codes in REST:

2xx - Success

  • 200 OK - Successful request
  • 201 Created - The resource is created
  • 204 No Content - Successful request, no content to return

3xx - Redirection

  • 301 Moved Permanently - Permanent redirection
  • 304 Not Modified - The resource is not modified (for caching)

4xx - Client Error

  • 400 Bad Request - Invalid request
  • 401 Unauthorized - Unauthorized access
  • 403 Forbidden - Forbidden access
  • 404 Not Found - The resource is not found
  • 409 Conflict - Conflict during processing

5xx - Server Error

  • 500 Internal Server Error - Internal server error
  • 503 Service Unavailable - The service is not available

Good practices for designing REST APIs:

URI Design

  • Use nouns, not verbs - /users, not /getUsers
  • Hierarchical structure - /users/123/posts
  • Lowercase letters - /api/users
  • Hyphen instead of underscore - /user-profiles
  • Versioning - /api/v1/users

Response Format

  • JSON as the main format
  • Standard response structure
  • Pagination for large collections
  • Sorting and filtering
  • Error handling with standard formats

Security

  • HTTPS always
  • Authentication & Authorization
  • Rate limiting
  • Input validation
  • CORS configuration

Examples for REST API Design:

Users API

  • GET /api/v1/users - Get all users
  • POST /api/v1/users - Create a new user
  • GET /api/v1/users/123 - Get a specific user
  • PUT /api/v1/users/123 - Update the entire user
  • PATCH /api/v1/users/123 - Partial update
  • DELETE /api/v1/users/123 - Delete the user

Nested Resources

  • GET /api/v1/users/123/posts - Get the posts of the user
  • POST /api/v1/users/123/posts - Create a new post for the user
  • GET /api/v1/users/123/posts/456 - Get a specific post

REST vs alternatives:

REST

  • HTTP-based
  • Stateless
  • Cacheable
  • Good for CRUD operations
  • Easy to understand

GraphQL

  • Single endpoint
  • Client-defined queries
  • No over-fetching
  • Good for complex queries
  • More complex implementation

gRPC

  • Protocol Buffers
  • High performance
  • Binary data
  • Good for microservices
  • More complex for web clients

Good practices for REST APIs:

  • Use the correct HTTP methods - GET, POST, PUT, DELETE, PATCH
  • Return appropriate HTTP status codes
  • Version your API - /api/v1, /api/v2
  • Use pagination for large datasets
  • Provide good error handling
  • Document your API - OpenAPI/Swagger
  • Implement rate limiting
  • Use HTTPS always
  • Maintain backward compatibility

Tools and ecosystem:

API Documentation

  • OpenAPI/Swagger - Standard for API documentation
  • Postman - API development and testing
  • API Blueprint - Documentation format

Development Frameworks

  • Express.js - For Node.js
  • Django REST Framework - For Python
  • Spring Boot - For Java
  • ASP.NET Core - For .NET
  • Ruby on Rails - For Ruby

Security

  • JWT - JSON Web Tokens for authentication
  • OAuth 2.0 - Authorization framework
  • CORS - Cross-Origin Resource Sharing

Conclusion:

REST is one of the most popular and widely used architectural styles for designing web APIs. Its simplicity, use of standard HTTP protocols and flexibility make it an ideal choice for many applications, especially those that require an easy-to-understand and maintainable API.

Remember: REST is not just about using HTTP methods, but following a set of architectural principles that ensure scalability, reliability and performance of your system.