Understanding REST and Best Practices for RESTful API Design

REST was introduced in 2000 by Roy Fielding in his doctoral dissertation; it has profoundly influenced web software design. The term stands for Representational State Transfer, which can be dissected into three key components.

Resource

A resource is any entity on the Internet—text, image, audio, video—identified uniquely by a URI. The URI points to the resource's location, not its representation; file extensions like .html are optional and belong to the representation layer.

Representational

Resources can be represented in various formats such as xml , html , json , PNG , JPEG , etc. The desired representation is specified in HTTP request headers Accept and Content-Type .

State Transfer

State changes are performed via HTTP verbs: GET to retrieve, POST to create, PUT to replace, PATCH to modify partially, and DELETE to remove resources.

REST Summary

Use URIs to locate resources.

Describe the representation with the Content-Type header.

Use HTTP verbs to express operations on resources.

RESTful API Design Summary

With the rise of mobile and web clients, a consistent mechanism for client‑server communication is essential; RESTful APIs fulfill this need.

URL Formatting

Follow RFC3986: URLs are case‑sensitive; use lowercase letters. Separate multi‑word segments with hyphens ( - ) rather than underscores ( _ ) for readability.

/api/featured-post/    # GOOD
/api/featured_post/    # WRONG

Protocol

Expose APIs over HTTPS to improve security; the protocol itself does not affect RESTfulness.

Domain

Host APIs on a dedicated domain, e.g., https://api.example.com/v1 or include the version in the path like https://www.example.com/api/v1 .

Versioning

Place the version number in the URL.

https://api.example.com/v1/

Naming Conventions

Use plural nouns to represent collections, matching database table names, e.g., /students , /schools , /employees .

https://api.example.com/v1/students
https://api.example.com/v1/schools
https://api.example.com/v1/employees

Avoid Verbs in URLs

URLs should denote resources (nouns); actions are expressed via HTTP verbs. When an operation cannot be mapped cleanly, a verb may be used as a sub‑resource, e.g., /search or /articles/{id}/publish .

HTTP Verb Usage

GET – retrieve a resource.

POST – create a new resource.

PUT – replace an existing resource.

PATCH – partially update a resource.

DELETE – remove a resource.

GET    https://api.example.com/v1/schools          # list schools
POST   https://api.example.com/v1/schools          # create school
GET    https://api.example.com/v1/schools/ID       # get school details
DELETE https://api.example.com/v1/schools/ID       # delete school
GET    https://api.example.com/v1/schools/ID/students   # list students of a school
DELETE https://api.example.com/v1/schools/ID/students/ID # delete a student

HTTP Status Codes

200 OK – successful GET.

201 CREATED – successful POST/PUT/PATCH.

204 NO CONTENT – successful DELETE.

400 BAD REQUEST – client error.

401 UNAUTHORIZED – authentication failure.

404 NOT FOUND – resource does not exist.

500 INTERNAL SERVER ERROR – server error.

Other Recommendations

Use OAuth 2.0 for authentication and prefer JSON as the response format for its readability and wide language support.