REST API Design Made Simple
What REST API Means
REST API is abbreviation for:
- Representational State Transfer Application Programming Interface
REST APIs give us a structured way to represent and access server data.
They define how:
client sends requests
server responds with data
Most modern frontend and backend applications communicate using REST APIs.
Resources in REST Architecture
Resources are the main entities/data being managed inside a REST API.
Examples:
users
products
orders
posts
Resources are represented using routes.
Example:
/users
/products
/orders
For this blog, we’ll mainly use:
users as the resource example.
HTTP Methods
REST APIs work heavily using HTTP methods.
Our CRUD operations are deeply connected to these HTTP requests.
| CRUD Operation | HTTP Method |
|---|---|
| Create | POST |
| Read | GET |
| Update | PUT |
| Delete | DELETE |
The method names themselves are meaningful enough:
GET → retrieve data
POST → create/send data
PUT → update data
DELETE → remove data
GET
GET helps us retrieve data from the server. It is mainly used for reading resources.
Examples:
GET /users
GET /users/1
Usually:
GET requests do not modify data
only fetch information
POST
POST is used to create or send new data to the server.
Example:
POST /users
{
"name": "John"
}
POST requests commonly contain data inside the request body.
PUT
PUT is used to update existing data. It generally updates/replaces the whole resource.
Example:
PUT /users/1
{
"name": "Updated John"
}
Do not confuse:
PUT
with:PATCH
Usually:
PUT → full update
PATCH → partial update
DELETE
DELETE is used to remove data from the server.
Example:
DELETE /users/1
This removes the specific resource identified by the route.
Status Codes Basics
Status codes are small numeric responses returned by the server.
They provide a quick way to understand:
whether request succeeded
failed
created something
had an error
Often beginners ignore status codes, but they are extremely important. Without even accessing the response body:
status codes already tell us a lot about the response.
Common Status Codes
| Status Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Resource Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 500 | Internal Server Error |
Example
{
"status": 404,
"message": "User not found"
}
Mapping Status Codes Properly
While status codes may seem like simple numbers:
properly mapping them to responses requires good API design discussion.
Example:
creating resource →
201invalid request →
400unauthorized request →
401
Choosing proper status codes makes APIs:
clearer
easier to debug
more standardized
Designing Routes Using REST Principles
REST routes should:
represent resources clearly
remain clean and predictable
Good route examples:
/users
/users/1
/products
/orders/20
Avoid unnecessary action-based routes like:
/getUsers
/createUser
/deleteUser
REST focuses more on:
resources
than:actions in route names
Actions are already represented using:
GET
POST
PUT
DELETE
Example Resource: Users
A simple users REST API may look like:
GET /users
GET /users/1
POST /users
PUT /users/1
DELETE /users/1
Each route performs a different operation on the same resource.
Why REST APIs Became Popular
REST APIs became popular because they are:
simple
scalable
readable
language independent
Almost every modern web application today communicates using APIs based on REST principles.