Understanding HTTP Status Codes and Methods in REST APIs

Learn HTTP status codes in depth, along with HTTP methods used in REST APIs, with real-world examples and best practices for backend development.

HTTP status codes and HTTP methods are the foundation of communication between client and server in web applications. As a backend developer, understanding them properly is essential for building scalable and production-ready APIs.

What are HTTP Status Codes?

HTTP status codes are three-digit numbers returned by the server to indicate the result of a client’s request. They are grouped into five categories.

1. 1xx – Informational Responses

These codes indicate that the request has been received and the process is continuing.

• 100 Continue: The server has received part of the request and expects the rest.

• Rarely used in typical REST APIs but important in low-level communication.

2. 2xx – Success Responses

These indicate that the request was successfully processed.

• 200 OK: The request was successful, and the response contains the requested data.

• 201 Created: A new resource was successfully created (commonly used in POST APIs).

• 204 No Content: The request was successful, but there is no content to return (used in DELETE operations).

Example:

Creating a user in an e-commerce app returns 201 Created.

3. 3xx – Redirection Responses

These indicate that further action is needed to complete the request.

• 301 Moved Permanently: Resource has been permanently moved to a new URL.

• 302 Found: Temporary redirection.

Used mostly in web applications, not very common in REST APIs.

4. 4xx – Client Error Responses

These indicate that there is an issue with the client request.

• 400 Bad Request: Invalid request data or missing parameters.

• 401 Unauthorized: Authentication is required.

• 403 Forbidden: Client does not have permission.

• 404 Not Found: Resource not found.

Real-world Example:

If a user tries to fetch a product that doesn’t exist, return 404 Not Found.

5. 5xx – Server Error Responses

These indicate that the server failed to process a valid request.

• 500 Internal Server Error: Generic server failure.

• 502 Bad Gateway: Invalid response from another server.

• 503 Service Unavailable: Server is down or overloaded.

These errors should be handled properly to avoid exposing internal details.

HTTP Methods (Verbs)

HTTP methods define the type of operation the client wants to perform.

1. GET

Used to retrieve data from the server.

• Safe and idempotent

• Example: Get user details

@GetMapping("/users/{id}")

2. POST

Used to create new resources.

• Not idempotent

• Example: Create a new user

@PostMapping("/users")

3. PUT

Used to update an existing resource completely.

• Idempotent

• Example: Update full user details

@PutMapping("/users/{id}")

4. PATCH

Used for partial updates.

• Only updates specific fields

@PatchMapping("/users/{id}")

5. DELETE

Used to delete a resource.

• Idempotent

@DeleteMapping("/users/{id}"

Difference Between PUT and PATCH (with Real-World Example)

Both PUT and PATCH are used to update resources in REST APIs, but they work differently.

PUT (Full Update)

• Replaces the entire resource

• If a field is missing, it may be overwritten or set to null

• Idempotent (same request produces the same result)

Example:

@PutMapping("/users/{id}")public StringupdateUser(@PathVariable Long id,@RequestBody User user) {return"User updated";
}

Request Body:

{"name":"Ayush","email":"ayush@gmail.com"}

This replaces the complete user object in the database.

PATCH (Partial Update)

• Updates only specific fields

• Does not affect other fields

• More efficient for small updates

Example:

@PatchMapping("/users/{id}")public StringupdateUserEmail(@PathVariable Long id,@RequestBody Map<String, Object> updates) {return"User partially updated";
}

Request Body:

{"email":"newemail@gmail.com"}

Only the email field will be updated.

Real-World Scenario (E-commerce)

User Profile:

{"name":"Ayush","email":"ayush@gmail.com","address":"Kanpur"}

• PUT → Update full profile (name, email, address required)

• PATCH → Update only address ("address": "Lucknow")

Key Differences

PUT is used to update the entire resource, while PATCH is used to update only specific fields of a resource.