Mastering RESTful API Design: HTTP Methods, Principles, and Status Codes

1. Using HTTP Methods to Build RESTful APIs

HTTP defines nine methods; the five most frequently used in RESTful API design are POST (create), GET (read), PUT (full update), PATCH (partial update), and DELETE (remove). Each method maps to a specific operation on a resource.

POST – Create a new resource, e.g., /users GET – Retrieve data, e.g., /users/{id} for a single record or /users?limit=1&offset=10 for a list

PUT – Replace an entire resource, e.g., /users/{id} PATCH – Modify part of a resource, e.g., /users/{id} (partial update)

DELETE – Remove a resource, e.g., /users/{id} Methods such as HEAD, TRACE, OPTIONS, and CONNECT are rarely used in RESTful APIs but are defined in RFC2616 for specialized scenarios.

2. API Design Principles

Adopt conventional, concise naming for endpoints.

Introduce versioning to support system evolution and compatibility.

Design query parameters for filtering, sorting, and searching in a clean manner.

Return data in a consistent format (prefer JSON) and consider compression (e.g., GZIP).

Use appropriate HTTP status codes and provide clear error messages.

Implement token‑based authentication and authorization mechanisms.

Provide pagination for large result sets.

Handle related resources efficiently in responses.

Enable HTTP caching to improve network efficiency.

Maintain stateless communication; the client should manage session state.

Apply layered architecture to limit component visibility and responsibilities.

Enforce rate limiting to protect the service.

Prefer HTTPS for all endpoints, especially those involving authentication.

3. HTTP Status Codes and Error Responses

Instead of always returning 200 OK, APIs should use the HTTP status codes defined by the protocol to convey the result of a request.

Data‑related errors 400 Bad Request – Incomplete or unparsable request. 422 Unprocessable Entity – Request is syntactically correct but semantically invalid. 404 Not Found – Requested resource does not exist. 409 Conflict – Resource state conflict (e.g., duplicate entry).

Authentication/Authorization errors 401 Unauthorized – Missing or invalid access token. 403 Forbidden – Valid token but insufficient permissions.

Standard status codes 200 OK – Successful request. 500 Internal Server Error – Unexpected server‑side failure.