Best Practices for RESTful API Design: URL Structure, Status Codes, and Server Responses

1. URL Design

The core idea of RESTful APIs is to use a verb + object pattern, where the HTTP method (GET, POST, PUT, PATCH, DELETE) represents the verb and the path (e.g., /articles ) is the noun object.

# GET: Read
# POST: Create
# PUT: Update
# PATCH: Partial update
# DELETE: Delete

If a client can only send GET or POST, the server must support X-HTTP-Method-Override to simulate PUT, PATCH, or DELETE.

POST /api/Person/4 HTTP/1.1
X-HTTP-Method-Override: PUT

The object part of the URL should be a noun, not a verb, and it is recommended to use plural nouns for collections (e.g., /articles instead of /article ).

# /getAllCars   (incorrect)
# /createNewCar (incorrect)
# /deleteAllRedCars (incorrect)

Avoid deep hierarchical URLs; use query strings for secondary filters.

# Bad: GET /authors/12/categories/2
# Better: GET /authors/12?categories=2

Example of a query‑string approach for published articles:

# GET /articles?published=true

2. Status Codes

Responses must include precise HTTP status codes. The five classes are 1xx (informational), 2xx (success), 3xx (redirection), 4xx (client error), and 5xx (server error).

# 1xx: informational
# 2xx: success
# 3xx: redirection
# 4xx: client error
# 5xx: server error

Common success codes:

# GET: 200 OK
# POST: 201 Created
# PUT: 200 OK
# PATCH: 200 OK
# DELETE: 204 No Content

Additional useful codes include 202 Accepted for asynchronous operations and 303 See Other for POST/PUT/DELETE redirects.

HTTP/1.1 303 See Other
Location: /api/orders/12345

Typical client‑error codes:

400 Bad Request : malformed request

401 Unauthorized : missing or invalid credentials

403 Forbidden : authenticated but not permitted

404 Not Found : resource does not exist

405 Method Not Allowed : HTTP method not allowed

429 Too Many Requests : rate limit exceeded

Typical server‑error codes:

500 Internal Server Error : unexpected failure

503 Service Unavailable : maintenance or overload

3. Server Responses

APIs should return JSON objects rather than plain text, and set Content‑Type: application/json . Clients must also send Accept: application/json .

GET /orders/2 HTTP/1.1
Accept: application/json

Never return a 200 status code for an error; instead use the appropriate error code and include error details in the JSON body.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payload.",
  "detail": { "surname": "This field is required." }
}

Provide hypermedia links (HATEOAS) so clients can discover related resources without memorizing URLs.

{
  "status": "In progress",
  "links": [
    { "rel": "cancel", "method": "delete", "href": "/api/status/12345" },
    { "rel": "edit",   "method": "put",    "href": "/api/status/12345" }
  ]
}

Reference links:

https://blog.florimondmanca.com/restful-api-design-13-best-practices-to-make-your-users-happy https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design