Mastering RESTful API Design: Principles, Best Practices, and Real-World Examples

What is RESTful?

REST (Representational State Transfer) is an architectural style defined by a set of constraints that, when satisfied, enable scalable, stateless client‑server communication. A system that follows these constraints is called a RESTful API.

Key Design Guidelines

1. Domain

Prefer a dedicated domain for the API, e.g.: https://api.example.com If a dedicated domain is unavailable, use a sub‑path on an existing domain: https://www.example.com/api In the URL, https is the protocol, the host (e.g., www.example.com) identifies the server, and the path (e.g., /api) identifies the API entry point.

2. Versioning

Include the API version in the URL so that clients can target a specific contract:

https://www.example.com/api/v1.0/students
https://www.example.com/api/v1.1/students
https://www.example.com/api/v2.0/students

Versioning can also be expressed via the Accept header, but URL‑based versioning is more discoverable:

Accept: application/vnd.example.student+json; version=1.0

3. Endpoints (Path)

Endpoints should be nouns that map to resources, typically using plural forms that correspond to database tables. Example of a well‑designed set of endpoints for a students resource:

GET    /students               # list all students
POST   /students               # create a new student
GET    /students/{id}          # retrieve a specific student
PATCH  /students/{id}          # partially update a student
PUT    /students/{id}          # fully replace a student
DELETE /students/{id}          # delete a student

4. HTTP Verbs

Map CRUD operations to HTTP methods:

GET – retrieve resources (safe, idempotent)

POST – create a new resource (non‑idempotent)

PUT – replace an entire resource (idempotent)

PATCH – partially modify a resource (non‑idempotent)

DELETE – remove a resource (idempotent)

Additional verbs such as HEAD (metadata only) and OPTIONS (capabilities) are useful for advanced scenarios.

5. Filtering, Pagination, and Sorting

Large collections should support query parameters that limit the result set, offset the start position, and order the data. Common parameters:

?limit=10               # maximum number of items returned
?offset=20              # skip the first 20 items
?page=2&per_page=50    # page‑based pagination
?sortby=score&order=asc

Both path‑based and query‑parameter approaches are acceptable, e.g.:

GET /classes/12/students
GET /students?class_id=12

6. HTTP Status Codes

Use standard status codes to convey the outcome of a request. Typical codes include:

200 OK – successful GET

201 Created – successful POST/PUT/PATCH that created a resource

202 Accepted – request accepted for asynchronous processing

204 No Content – successful DELETE

400 Bad Request – malformed request syntax

401 Unauthorized – authentication required or failed

403 Forbidden – authenticated but not allowed

404 Not Found – resource does not exist

422 Unprocessable Entity – validation error on input

500 Internal Server Error – unexpected server failure

7. Error Payloads

For 4xx responses, return a JSON object that contains an error key with a human‑readable message:

{
  "error": "Invalid API key"
}

8. Response Body Conventions

Structure the response body according to the operation:

GET collection → JSON array of resource objects

GET single resource → JSON object

POST → JSON representation of the newly created object

PUT / PATCH → JSON representation of the updated object

DELETE → empty body (or 204 status)

9. Hypermedia (HATEOAS)

Whenever possible, include links to related actions in the response so that clients can discover the API without external documentation. Example (GitHub API root):

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations"
  // ...
}

10. Data Format

JSON is the de‑facto payload format for RESTful APIs because of its lightweight syntax and native support in JavaScript. An equivalent XML representation is much more verbose and is rarely used in modern APIs.

# JSON example
{
  "name": "XiaoMing",
  "age": 12,
  "gender": "male"
}