HTTP Methods (Verbs) and Their Semantics

What You'll Learn:

• Understanding safe, idempotent, and cacheable HTTP methods

• Proper usage of GET, POST, PUT, PATCH, DELETE

• RESTful API design principles with HTTP methods

Detailed Explanation:

Core HTTP Methods

1. GET - Retrieve Resources

• Safe: No server state modification

• Idempotent: Same request = same result

• Cacheable: Responses can be cached

• Request Body: Should not have (ignored by servers)

GET /api/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json

2. POST - Create Resources

• Not Safe: Modifies server state

• Not Idempotent: Multiple identical requests may create multiple resources

• Request Body: Contains resource data

POST /api/users HTTP/1.1
Content-Type: application/json
Content-Length: 56

{"name": "Jane Smith", "email": "jane@example.com"}

3. PUT - Update/Replace Resources

• Not Safe: Modifies server state

• Idempotent: Multiple identical requests = same result

• Request Body: Complete resource representation

PUT /api/users/123 HTTP/1.1
Content-Type: application/json
Content-Length: 78

{"id": 123, "name": "Jane Smith", "email": "jane.smith@example.com"}

4. PATCH - Partial Update

• Not Safe: Modifies server state

• Not Idempotent: Depends on patch content

• Request Body: Contains partial modifications

PATCH /api/users/123 HTTP/1.1
Content-Type: application/json-patch+json
Content-Length: 72

[{"op": "replace", "path": "/email", "value": "new.email@example.com"}]

5. DELETE - Remove Resources

• Not Safe: Modifies server state

• Idempotent: Multiple identical requests = same result

DELETE /api/users/123 HTTP/1.1
Host: api.example.com
Less Common Methods

6. HEAD - Retrieve Headers Only

HEAD /api/users/123 HTTP/1.1
Host: api.example.com

7. OPTIONS - Discover Supported Methods

OPTIONS /api/users HTTP/1.1
Host: api.example.com

Response:

HTTP/1.1 200 OK
Allow: GET, POST, PUT, DELETE, OPTIONS, HEAD

Method Properties Table

RESTful API Design Examples

Collection Resource:

GET    /api/users           # List all users
POST   /api/users           # Create new user

Singleton Resource:

GET    /api/users/123       # Get user 123
PUT    /api/users/123       # Replace user 123
PATCH  /api/users/123       # Partially update user 123
DELETE /api/users/123       # Delete user 123

Sub-resources:

GET    /api/users/123/orders    # Get orders for user 123
POST   /api/users/123/orders    # Create order for user 123

Practical Implementation

Spring Boot Controller Example:

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping
    public List<User> getUsers() {
        return userService.findAll();
    }
    
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
    
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public User createUser(@RequestBody @Valid CreateUserRequest request) {
        return userService.create(request);
    }
    
    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody @Valid UpdateUserRequest request) {
        return userService.update(id, request);
    }
    
    @PatchMapping("/{id}")
    public User patchUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
        return userService.patch(id, updates);
    }
    
    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }
}