REST (Representational State Transfer) is an architectural style for designing networked web API services over HTTP.
HTTP Verbs & Semantics
| Method | Target Action | Safe | Idempotent |
|---|---|---|---|
GET |
Retrieve resource representation | Yes | Yes |
POST |
Create a new subordinate resource | No | No |
PUT |
Replace entire resource representation | No | Yes |
PATCH |
Partially update resource properties | No | No |
DELETE |
Delete resource | No | Yes |
HEAD |
Retrieve headers without response body | Yes | Yes |
OPTIONS |
Query supported HTTP methods for endpoint | Yes | Yes |
Common HTTP Response Status Codes
Success (2xx)
200 OK: Request succeeded (body contains representation).201 Created: Resource created successfully (Locationheader indicates URI).202 Accepted: Request accepted for asynchronous processing.204 No Content: Action succeeded, no response body returned (common onDELETE).
Client Errors (4xx)
400 Bad Request: Malformed syntax, invalid parameters, or validation failure.401 Unauthorized: Authentication missing or invalid.403 Forbidden: Authenticated user lacks permission to access resource.404 Not Found: Resource URI does not exist.409 Conflict: Request conflicts with current resource state (e.g., duplicate unique key).422 Unprocessable Entity: Well-formed request failed semantic domain validation.429 Too Many Requests: Rate limit exceeded.
Server Errors (5xx)
500 Internal Server Error: Generic unhandled server-side failure.502 Bad Gateway: Upstream server returned invalid response.503 Service Unavailable: Server overloaded or undergoing maintenance.
Standard JSON Error Envelope
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The email address provided is already registered.",
"details": [
{
"field": "email",
"issue": "unique_constraint_violated"
}
]
}
}