Contents (12)
RESTful API Architecture
REST (Representational State Transfer) is a software architecture style created to provide guidelines for developing the Web and to describe its structure.
1. Characteristics of REST Architecture
The core of a RESTful API is to see a URL not as an endpoint but as a single resource, and to be consistent so that the API becomes predictable. Below are the characteristics that REST architecture is said to have.
1.1 Stateless (Statelessness)
Client information isn't stored across client-server requests, and each request must be independent of the others.
1.2 Client-Server Structure
It consists of clients, servers, and resources, and requests are made over HTTP.
1.3 Data Caching
It makes caching possible to minimize interactions between the client and the server.
1.4 Uniform Interface
Resources must be identifiable, and they must be distinguishable from the representations sent to the client.
Resources must also be manipulated through the representations that are received.
The client's self-descriptive messages must contain enough information to explain how the information should be processed. (Content-type, method, encoding, etc.)
1.5 Layered Architecture Support
The server can have a layered system organized into a hierarchy (security, load balancing, etc.).
1.6 Code on Demand
When it receives a request, the server can send executable code to the client to extend the client's functionality.
2. Methods and Statuses at a Glance
In a RESTful API, actions on resources are expressed through HTTP methods, the server handles each request according to its method, and it expresses the state of the response by sending a status code in the Response.
2.1 Methods
Method | Description | Main Use | Idempotent | Safe | Example URI |
|---|---|---|---|---|---|
GET | Retrieve a resource | Fetching data | ✅ Yes (making the same request multiple times gives the same result) | ✅ Yes (no change to server state) | /users/1 |
POST | Create a resource | Adding data | ❌ No | ❌ No | /users |
PUT | Modify an entire resource | Full data update | ✅ Yes | ❌ No | /users/1 |
PATCH | Modify part of a resource | Partial data update | ❌ Generally no (depends on the server implementation) | ❌ No | /users/1 |
DELETE | Delete a resource | Deleting data | ✅ Yes (the same response is possible even if it's already deleted) | ❌ No | /users/1 |
OPTIONS | Check the supported methods | CORS preflight requests, etc. | ✅ Yes | ✅ Yes | /users |
HEAD | Retrieve only the resource's headers (no body) | Checking metadata | ✅ Yes | ✅ Yes | /users/1 |
2.2 Status
Status | Status Code | Meaning | Description | Usage Example |
|---|---|---|---|---|
(2xx) | 200 OK | Request succeeded | Used for GET, PUT, PATCH, DELETE, etc. | Data retrieved successfully |
201 Created | Created | Used when a resource is created with a POST request | Signing up, writing a post, etc. | |
204 No Content | No Content | When the request succeeded but there's no response body | No response body after a successful DELETE or PUT | |
(3xx) | 301 Moved Permanently | Moved Permanently | The resource has moved permanently | Notifying of a URL change |
302 Found | Moved Temporarily | The resource is temporarily at a different location | Redirecting after login | |
304 Not Modified | Not Modified | The cached resource can be used as is | Conditional GET (If-Modified-Since, etc.) | |
(4xx) | 400 Bad Request | Bad Request | Invalid parameters, etc. | Missing fields, JSON parsing failure |
401 Unauthorized | Authentication Required | Login required or token error | No JWT / expired JWT | |
403 Forbidden | Forbidden | When you don't have permission | Admin-only access | |
404 Not Found | Resource Not Found | Request for a URI that doesn't exist | When looking something up with a wrong ID | |
409 Conflict | Conflict | When creating a duplicate resource, etc. | Creating a duplicate with the same ID, etc. | |
422 Unprocessable Entity | Unprocessable | The format is valid, but the meaning is wrong | Form validation failure, etc. | |
(5xx) | 500 Internal Server Error | Internal Server Error | An exception occurred inside the server | Unexpected error |
502 Bad Gateway | Bad Gateway | The server received an invalid response | Proxy or gateway problems | |
503 Service Unavailable | Service Unavailable | The server is under maintenance or overloaded | Server down, maintenance | |
504 Gateway Timeout | Gateway Timeout | Delayed response | When the backend is slow to respond |
3. Richardson Maturity Model
Richardson defined a four-level maturity model for applying REST APIs well.

