Understanding REST and RESTful API Design Principles and Best Practices

REST (Representational State Transfer) is an architectural style introduced by Dr. Roy Fielding in 2000, defining a set of constraints for building scalable web services.

Principles of REST include abstracting everything as resources, assigning each a unique identifier (URI), supporting multiple representations (e.g., JSON, XML), keeping resource identifiers immutable, and ensuring stateless interactions.

Resources are information entities that can be uniquely identified by a URI; examples include libraries, floors, or services in an application.

Representations describe the state of a resource at a specific moment and can be transferred between client and server using formats such as HTML, XML, JSON, plain text, images, video, or audio, indicated via HTTP Accept and Content-Type headers.

State Transfer occurs when a client obtains a representation of a resource, manipulates it, and sends it back to the server, thereby changing the application state.

RESTful API

A RESTful API follows the REST constraints, using nouns in URIs and HTTP methods to express actions, unlike traditional RPC‑style APIs that embed verbs in endpoint names.

Design Guidelines

When designing APIs, URIs should locate resources (nouns) while HTTP verbs (GET, POST, PUT, PATCH, DELETE, HEAD) perform actions. Avoid verbs in URIs and prefer resource‑oriented modeling.

Example of non‑standard verb‑based endpoints:

/getCustomers
/getCustomersByName
/getCustomersByPhone
/getNewCustomers
/verifyCredit
/saveCustomer
/updateCustomer
/deleteCustomer

Standard RESTful endpoints use noun‑based URIs:

GET /Api/Users/{id}
POST /Api/Orders
POST /Api/Orders/{id}/OrderItems
PATCH /Api/Orders/{id}/Address
DELETE /Api/Orders/{id}

URI design should consider aggregation boundaries, avoiding deep nesting that mirrors database tables. Instead, model aggregates (e.g., Order with its OrderItems) as cohesive resources.

HTTP Verbs

Common HTTP methods used in RESTful APIs:

GET – retrieve a resource

HEAD – retrieve metadata only

POST – create a new resource or perform complex queries

PUT – replace an entire resource

PATCH – partially update a resource

DELETE – remove a resource

URI Versioning

Versioning strategies include embedding the version in the path (e.g., GET /Api/v2/Orders/{id} ), as a query parameter (e.g., GET /Api/Orders/{id}?version=2 ), or via a custom HTTP header.

Maturity Model

Leonard Richardson’s API maturity model defines four levels:

Level 0 – single URI with POST for all actions

Level 1 – separate URIs for each resource

Level 2 – use HTTP methods to define actions

Level 3 – incorporate hypermedia (HATEOAS)

Most implementations aim for Level 2 or 3 to achieve true RESTfulness.

Status Codes

HTTP status codes convey request outcomes without additional payload wrappers. Typical categories are informational (100–199), successful (200–299), redirection (300–399), client errors (400–499), and server errors (500–599).

Example JSON response wrapper (often unnecessary when using proper status codes):

{
"code": 200,
"message": "",
  "data": {}
}

For detailed guidance, refer to the listed reference documents.