How REST API Works - Understanding Web API Design Principles

What is a REST API

REST (Representational State Transfer) is a web service design style proposed by Roy Fielding in 2000. A REST API refers to a Web API built following these design principles.

In modern web service development, REST API is the most widely used API design approach.

What is an API: API stands for Application Programming Interface, a mechanism for exchanging data between different software systems.

The Six Design Principles of REST

1. Client-Server Separation

Separates the client (frontend) and server (backend), allowing each to be developed and evolved independently.

2. Stateless

Each request must be self-contained. The server does not maintain client state.

3. Cacheable

Responses must explicitly indicate whether they are cacheable.

4. Uniform Interface

Unifies how resources are manipulated. This is the most important characteristic of REST APIs.

5. Layered System

Clients are unaware of whether they are communicating directly with the server or through intermediate servers.

6. Code on Demand (Optional)

Code can be sent from the server to the client for execution.

HTTP Methods and CRUD Operations

What is Idempotency: A property where executing the same operation multiple times produces the same result.

Resource and URL Design

# Resource collections (use plural form)
GET    /api/users          # Get list of users
POST   /api/users          # Create new user

# Specific resource
GET    /api/users/123      # Get user with ID=123
PUT    /api/users/123      # Update user with ID=123
DELETE /api/users/123      # Delete user with ID=123

# Nested resources
GET    /api/users/123/posts    # Get posts for user 123

HTTP Status Codes

Success (2xx)

• 200 OK - Request successful
• 201 Created - Resource creation successful
• 204 No Content - Success (no response body)

Client Errors (4xx)

• 400 Bad Request - Invalid request
• 401 Unauthorized - Authentication required
• 403 Forbidden - No access permission
• 404 Not Found - Resource does not exist

Server Errors (5xx)

• 500 Internal Server Error - Server internal error
• 503 Service Unavailable - Service temporarily unavailable

Summary

REST API is a simple and easy-to-understand API design approach that leverages the characteristics of the HTTP protocol. By representing resources with URLs and operations with HTTP methods, a unified interface is achieved.