Introduction
This week, I learned the fundamentals of HTTP (HyperText Transfer Protocol) and REST (Representational State Transfer) API conventions.
The main focus was understanding how a client communicates with a server through HTTP requests and responses, how different HTTP methods are used, how status codes communicate the result of a request, and how REST APIs should be structured using predictable resource-based URLs.
As part of the practical task, I extended a raw Node.js HTTP server to follow REST conventions by implementing GET, POST, PUT, and DELETE routes with appropriate status codes and HTTP headers.
1. HTTP Request and Response Cycle
HTTP is a protocol used for communication between a client and a server.
A typical communication follows this process:
Client
|
| HTTP Request
↓
Server
|
| HTTP Response
↓
Client
For example, when a client requests a list of users:
GET /users
The server processes the request and sends a response:
200 OK
Content-Type: application/json
{
"users": [
{
"id": 1,
"name": "Swaroop"
}
]
}
An HTTP request can contain:
- Method – GET, POST, PUT, PATCH, DELETE
- URL/Path – identifies the requested resource
- Headers – provide additional information
- Body – contains data sent to the server when required
The response generally contains:
- Status code
- Response headers
- Response body
2. HTTP Methods
HTTP methods define what operation the client wants to perform.
GET
GET is used to retrieve data.
GET /users
It can return a list of users.
GET /users/10
It can return a specific user.
POST
POST is generally used to create a new resource.
POST /users
Example request body:
{
"name": "Swaroop",
"email": "swaroop@example.com"
}
If the user is successfully created, the server can return:
201 Created
PUT
PUT is used to replace or completely update a resource.
PUT /users/10
For example:
{
"name": "Sai Swaroop",
"email": "swaroop@example.com"
}
PATCH
PATCH is used when only part of a resource needs to be updated.
PATCH /users/10
For example, if only the name needs to change:
{
"name": "Sai Swaroop"
}
DELETE
DELETE is used to remove a resource.
DELETE /users/10
If the deletion is successful and there is no response body, the server can return:
204 No Content
3. Idempotency
One important concept I learned was idempotency.
Idempotency means that making the same request multiple times has the same intended final effect as making it once.
For example:
PUT /users/10
with:
{
"name": "Swaroop"
}
If this same request is sent multiple times, the final state of user 10 remains the same.
This property is useful because HTTP requests can sometimes be retried due to network problems.
Commonly:
GET → Idempotent
PUT → Idempotent
DELETE → Idempotent
POST → Not generally idempotent
PATCH → Depends on the operation
Idempotency helps make API behavior more predictable when requests are repeated.
4. HTTP Status Codes
HTTP status codes tell the client what happened when the server processed a request.
The major categories are:
2xx → Success
3xx → Redirection
4xx → Client Error
5xx → Server Error
For this week's practical work, I used the following status codes.
200 OK
Used when a request is successfully processed.
Example:
GET /users
Response:
200 OK
201 Created
Used when a new resource has been successfully created.
Example:
POST /users
Response:
201 Created
204 No Content
Used when the request succeeds but the server does not need to return a response body.
Example:
DELETE /users/10
Response:
204 No Content
400 Bad Request
Used when the client sends invalid or malformed data.
Example:
{
"name": ""
}
The server can respond with:
400 Bad Request
404 Not Found
Used when the requested resource does not exist.
Example:
GET /users/999
If user 999 does not exist:
404 Not Found
5. HTTP Headers
HTTP headers provide additional information about a request or response.
Content-Type
Content-Type tells the client what type of data is being sent.
For JSON APIs:
Content-Type: application/json
This tells the client that the response body contains JSON data.
Cache-Control
Cache-Control provides instructions related to caching.
For example:
Cache-Control: no-cache
or:
Cache-Control: max-age=3600
Caching can reduce unnecessary requests and improve performance when used appropriately.
Authorization
The Authorization header is commonly used to send authentication credentials or tokens.
For example:
Authorization: Bearer <token>
This allows the server to identify and authorize the client when authentication is implemented.
6. Statelessness
Another important REST concept I learned is statelessness.
A stateless API treats each request independently. The server should not need to depend on information stored from a previous request in order to understand the current request.
For example:
GET /users/10
Authorization: Bearer <token>
The request contains the information required by the server to process it.
Statelessness makes APIs easier to scale and reason about because requests can be handled independently by different server instances.
7. REST Resource Naming Conventions
REST APIs generally represent resources using nouns, rather than putting actions in the URL.
Non-conventional URLs
GET /getUsers
POST /createUser
GET /getUserById/10
DELETE /deleteUser/10
These URLs contain actions such as get, create, and delete.
REST-style URLs
GET /users
POST /users
GET /users/10
PUT /users/10
DELETE /users/10
Here, the URL identifies the resource:
/users
and the HTTP method describes the operation.
This makes APIs easier to understand and maintain.
8. REST API Route Structure
A simple user API can follow this structure:
| Method | Endpoint | Purpose | Status |
|---|---|---|---|
| GET | /users |
Get all users | 200 |
| POST | /users |
Create a user | 201 |
| GET | /users/:id |
Get one user | 200 / 404 |
| PUT | /users/:id |
Update a user | 200 / 404 |
| DELETE | /users/:id |
Delete a user | 204 / 404 |
The important idea is that the resource name remains /users, while the HTTP method determines the operation.
9. Practical Implementation
For the JavaScript cohort, I extended the raw Node.js HTTP server using the built-in http module.
The server was structured around REST-style routes:
GET /users
POST /users
PUT /users/:id
DELETE /users/:id
I also implemented appropriate response status codes:
200 → Successful GET/PUT
201 → Successful POST
204 → Successful DELETE
400 → Invalid request
404 → Resource not found
Basic headers were also included:
Content-Type: application/json
Cache-Control: ...
The goal was not just to make the routes work, but to make them follow common REST conventions.
10. REST Naming Review
After implementing the routes, I reviewed the API URLs to check whether they followed REST naming conventions.
Instead of:
/getUsers
/createUser
/deleteUser/10
I used:
/users
/users/10
The HTTP method communicates the operation:
GET /users → Read
POST /users → Create
PUT /users/10 → Update
DELETE /users/10 → Delete
This separates the resource from the operation and makes the API more predictable.
11. What I Learned
Through this week's learning and practical implementation, I understood:
- How the HTTP request/response cycle works
- The purpose of HTTP methods
- The difference between GET, POST, PUT, PATCH, and DELETE
- The concept of idempotency
- HTTP status code categories
- When to use 200, 201, 204, 400, and 404
- The purpose of HTTP headers
-
Content-Type,Cache-Control, andAuthorization - The concept of stateless APIs
- REST resource naming conventions
- How to design resource-based API endpoints
- How to extend a raw Node.js HTTP server with REST-style routes
- How to review existing API routes against REST conventions
Conclusion
HTTP and REST conventions provide a standard way for clients and servers to communicate.
Understanding methods, status codes, headers, idempotency, statelessness, and resource naming helped me move from simply creating working HTTP routes to designing APIs that are more predictable, consistent, and easier to understand.
The practical implementation of REST routes using the raw Node.js http module helped me connect the theoretical concepts with actual server-side code.
Top comments (0)