Best Practices for Designing RESTful APIs

1. URL Design

RESTful APIs should use a clear verb + noun pattern, where the HTTP method (GET, POST, PUT, PATCH, DELETE) represents the verb and the URL path represents the noun.

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

Verb Override

If a client can only use GET and POST, the server must accept POST with the X-HTTP-Method-Override header to indicate the intended verb (e.g., PUT).

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

Object Must Be a Noun

The URL (object) should be a noun, not a verb. For example, /articles is correct, while /getAllCars , /createNewCar , or /deleteAllRedCars are incorrect.

# /getAllCars
# /createNewCar
# /deleteAllRedCars

Plural URLs

When the URL represents a collection, use plural nouns (e.g., GET /articles to retrieve all articles) for consistency.

Avoid Multi‑level URLs

Instead of deep hierarchical paths like /authors/12/categories/2 , use query strings for secondary levels (e.g., /authors/12?categories=2 ).

# GET /authors/12?categories=2

Query‑string Example

To fetch published articles, prefer a query parameter:

# GET /articles?published=true

2. Status Codes

HTTP status codes are three‑digit numbers grouped into five categories.

# 1xx: Informational
# 2xx: Success
# 3xx: Redirection
# 4xx: Client Error
# 5xx: Server Error

2xx Success Codes

Use specific success codes for each method:

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

For asynchronous operations, return 202 Accepted with a task link.

HTTP/1.1 202 Accepted
{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

3xx Redirection Codes

APIs typically use 303 See Other for temporary redirects after POST/PUT/DELETE.

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

4xx Client Error Codes

Common client‑error codes include 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 410 Gone, 415 Unsupported Media Type, 422 Unprocessable Entity, and 429 Too Many Requests.

5xx Server Error Codes

Typically only 500 Internal Server Error and 503 Service Unavailable are needed for APIs.

3. Server Responses

Return JSON, Not Plain Text

Responses should be JSON objects with Content‑Type: application/json . Clients must send Accept: application/json in requests.

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

Do Not Return 200 on Errors

Never hide errors behind a 200 status; use the appropriate error status 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)

Include related links in responses to guide clients to next actions.

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

4. References

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