RESTful API Design Best Practices and Detailed Guidelines

RESTful is the most popular API design specification for web data interfaces. While its high‑level principles are easy to grasp, the details are often misunderstood. This article summarizes the essential design details to help you create clear and usable APIs.

1. URL Design

Verb + Noun

The core idea of RESTful is that each request consists of a verb (HTTP method) and a noun (resource). For example, GET /articles uses GET as the verb and /articles as the noun. The five standard HTTP verbs correspond to CRUD operations and must be uppercase.

# GET: Read
# POST: Create
# PUT: Update
# PATCH: Update (partial)
# DELETE: Delete

Verb Override

When a client can only use GET and POST, the server must accept POST with the X-HTTP-Method-Override header to simulate PUT, PATCH, or DELETE.

POST /api/Person/4 HTTP/1.1

X-HTTP-Method-Override: PUT

Noun Must Be a Noun

The resource part of the URL should be a noun, not a verb. Correct: /articles . Incorrect examples: /getAllCars , /createNewCar , /deleteAllRedCars .

# /getAllCars
# /createNewCar
# /deleteAllRedCars

Plural URLs

When the URL represents a collection, use plural nouns, e.g., GET /articles for all articles, and GET /articles/2 rather than /article/2 .

Avoid Multi‑Level URLs

Deep hierarchical URLs are hard to extend. Use query strings for secondary levels, e.g., GET /authors/12?categories=2 instead of /authors/12/categories/2 . For filtering, prefer GET /articles?published=true .

2. Status Codes

Codes Must Be Precise

Each response should include an appropriate three‑digit HTTP status code. 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

2xx Codes

Typical success codes:

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

202 Accepted indicates the request is accepted for asynchronous processing.

HTTP/1.1 202 Accepted

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

3xx Codes

APIs rarely use 301/302 redirects. The most relevant is 303 See Other, which is used after POST/PUT/DELETE to point to another URL.

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

4xx 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 Codes

Server‑error codes are usually 500 Internal Server Error and 503 Service Unavailable.

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 the request header.

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

Do Not Return 200 on Errors

Returning 200 with an error payload hides the failure. Use the appropriate error status code and include details in the body.

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

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

Provide Links (HATEOAS)

Include related URLs in the response to guide clients, e.g., GitHub’s API returns feeds_url , followers_url , etc. A better practice separates links from other data.

HTTP/1.1 200 OK
Content-Type: application/json

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

4. References

RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca

API design, by Microsoft Azure