Understanding REST and Best Practices for RESTful API Design

Roy Fielding introduced the term REST (Representational State Transfer) in his 2000 PhD dissertation, influencing modern web architecture; REST abstracts the transfer of a resource's representation state.

Core Concepts

Resource : Anything accessible on the Internet (text, image, audio, video) identified uniquely by a URI. The URI points to the resource's location, not its format.

Representational : A resource 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 : Operations on resources are performed using HTTP verbs – GET to retrieve, POST to create, PUT to replace, PATCH to modify partially, and DELETE to remove.

RESTful API Design Summary

Use URIs to locate resources.

Describe the representation with the Content-Type header.

Use HTTP verbs to express actions on resources.

Formatting Conventions

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

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

Protocol, Domain, and Versioning

Expose APIs over HTTPS for security. Host APIs under a dedicated sub‑domain, e.g., https://api.example.com/v1 , or embed the version in the path.

Naming Guidelines

Use plural nouns in paths to reflect collections, e.g., /v1/students , /v1/schools , /v1/employees . Avoid verbs in URLs; let HTTP verbs convey actions. If an operation lacks a standard verb (e.g., search), a verb can be used in the path for clarity.

http://api.xxx.com/apiv3/search?timestamp=123213218&user_id=4192121&keyword=2134789

HTTP Verb Mapping

GET – retrieve a resource.

POST – create a new resource.

PUT – replace an existing resource.

PATCH – modify part of a resource.

DELETE – remove a resource.

GET    https://api.example.com/v1/schools               # list all schools
POST   https://api.example.com/v1/schools               # create a school
GET    https://api.example.com/v1/schools/{ID}          # get a specific school
DELETE https://api.example.com/v1/schools/{ID}          # delete a specific 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 specific 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‑side failure.

Other Recommendations

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