REST API Design Guide and Rules

This document provides an introduction to Application Programming Interfaces (APIs),

key terminologies for API developers, an explanation of REST APIs and their distinctions
from other API types, and a comprehensive list of 37 design rules for RESTful APIs as
outlined in the REST API Design Rulebook by Mark Massé (O'Reilly, 2012). The content
is formatted for clarity and can be printed or converted to a .docx file for professional
use.

What is an API?

An Application Programming Interface (API) is a set of rules, protocols, and tools that
allows different software applications to communicate with each other. APIs act as
intermediaries, enabling one program to request data or services from another without
needing to understand the internal workings of the other system. For example, a
weather app might use an API to retrieve real-time weather data from a remote server.

APIs are fundamental to modern software development, enabling:

• Modularity: Breaking down complex systems into reusable components.

• Interoperability: Allowing disparate systems (e.g., web, mobile, or desktop

applications) to work together.

• Scalability: Supporting the integration of new features or third-party services.

For developers, APIs simplify integration by providing standardized endpoints, data

formats, and protocols, making it easier to build applications that leverage external
services or data.

Key Terminologies for API Developers

Understanding the following terms is essential for API developers, as they form the
foundation of API design, implementation, and interaction. These terms are drawn from
the REST API Design Rulebook and general API development practices.

1. Resource: A web-based concept (e.g., a user, document, or collection) that can

be uniquely identified and manipulated via a URI. Resources are the core entities
in REST APIs.

2. URI (Uniform Resource Identifier): A string that uniquely identifies a resource

on the web (e.g., http://api.example.com/users/123). URIs are critical for
addressing resources in REST APIs.

3. HTTP (HyperText Transfer Protocol): The protocol used for communication

between clients and servers on the web. APIs use HTTP methods (e.g., GET,
POST) to perform actions on resources.
4. HTTP Method: Specific actions defined by HTTP, such as GET (retrieve), POST
(create), PUT (update), DELETE (remove), and OPTIONS (metadata). REST APIs
map these methods to resource operations.

5. Status Code: Numeric codes in HTTP responses (e.g., 200 OK, 404 Not Found)
that indicate the outcome of a request. They are crucial for communicating
success or failure.

6. Media Type: A format specification (e.g., application/json, application/xml) that

describes the structure of data exchanged in API requests and responses.

7. Representation: The formatted state of a resource (e.g., a JSON object) sent in a

response or request. It represents the resource's current state, not the resource
itself.

8. HATEOAS (Hypermedia as the Engine of Application State): A REST constraint

where resource representations include links to related resources, guiding
clients through available actions dynamically.

9. Client-Server: A REST architectural principle separating the client (request

initiator) and server (resource provider), allowing independent evolution of each.

10. Stateless: A REST constraint requiring each client request to contain all
necessary information, with no server-side session state, enhancing scalability.

11. Cache: A mechanism to store response data, reducing latency and server load.
REST APIs use headers like Cache-Control to manage caching.

12. Link: A reference to another resource (e.g., a URL in a JSON response) that
enables navigation or actions, central to hypermedia in REST.

13. Schema: A definition of a resource's structure (fields and links), used to validate
and version representations, often in formats like JSON Schema.

14. OAuth: An authorization protocol for securing API resources, allowing clients to
access protected data without sharing credentials.

15. CORS (Cross-Origin Resource Sharing): A mechanism to allow browser-based

clients to access resources from different origins, critical for JavaScript clients.

16. JSONP (JSON with Padding): A technique to bypass same-origin restrictions for
JavaScript clients, enabling cross-origin GET requests.

17. Entity Tag (ETag): A header used to track the version of a resource’s state,
supporting conditional requests and versioning.

18. Query Parameter: Part of a URI (e.g., ?name=John) used to filter, paginate, or
customize API responses.
These terms are critical for designing, implementing, and consuming APIs, particularly
REST APIs, as they underpin the architectural principles and practical considerations
outlined in the book.

What is a REST API and What Makes It Different?

A REST API (Representational State Transfer API) is a type of web API that adheres to the
architectural style of REST, as defined by Roy Fielding in his 2000 Ph.D. dissertation.
REST APIs enable clients (e.g., web or mobile applications) to interact with server
resources over HTTP, using a standardized, stateless, and resource-oriented approach.

REST API Principles

REST APIs are governed by six architectural constraints, which collectively define their
principles and ensure scalability, simplicity, and maintainability. These principles are
derived from Fielding’s work and elaborated in the REST API Design Rulebook (pages 23-
24).

1. Client-Server

o Description: Separates the client (which initiates requests) from the

server (which manages resources), allowing each to evolve
independently. For example, a mobile app (client) can be updated without
changing the server’s API.

o Purpose: Enhances portability of client applications and simplifies server

architecture.

o Example: A web app requests user data from api.example.com/users,

and the server responds without needing to know the app’s UI.

2. Stateless

o Description: Each client request must contain all information needed to

process it, with no reliance on server-stored session state. This means the
server does not retain data between requests.

o Purpose: Improves scalability by allowing servers to handle requests

independently and recover from failures easily.

o Example: A request to GET /users/123 includes authentication tokens in

the header, not stored server-side.

3. Cacheable

o Description: Responses must indicate whether they can be cached

(stored) by clients or intermediaries (e.g., proxies) to reduce latency and
 server load. Cache-control headers (e.g., Cache-Control: max-age=3600)
manage this.

o Purpose: Enhances performance and reduces redundant requests.

o Example: A GET /weather/city response with ETag allows the client to

cache the result and check for updates later.

4. Layered System

o Description: The architecture can include intermediaries (e.g., load

balancers, proxies, or gateways) without the client knowing the server’s
internal structure. Clients interact with a single endpoint, unaware of
layers.

o Purpose: Supports scalability, security, and encapsulation of legacy

systems.

o Example: A client accesses api.example.com, which routes through a

CDN and load balancer to the server.

5. Uniform Interface

o Description: Provides a standardized way to interact with resources

through four sub-constraints:

▪ Identification of Resources: Each resource is uniquely identified

by a URI (e.g., /users/123).

▪ Manipulation of Resources via Representations: Clients work

with resource representations (e.g., JSON) rather than the
resources themselves.

▪ Self-Descriptive Messages: Requests and responses include

metadata (e.g., headers like Content-Type) to describe their intent
and content.

▪ HATEOAS: Responses include hypermedia links to related

resources, enabling dynamic navigation (e.g., a user response with
a link to /users/123/orders).

o Purpose: Simplifies client-server interactions and ensures consistency

across APIs.

o Example: A GET /users/123 response includes a JSON representation and

links to related actions like DELETE /users/123.

6. Code-on-Demand (Optional)
 o Description: Servers can send executable code (e.g., JavaScript) to
clients to extend functionality, though this is rarely used in REST APIs due
to security and complexity concerns.

o Purpose: Increases client flexibility, but is optional and uncommon in

practice.

o Example: A server sends a JavaScript function to render a custom UI,

though most REST APIs avoid this.

These principles ensure REST APIs are scalable, maintainable, and aligned with web
standards, making them ideal for distributed systems.

What Makes REST APIs Different?

REST APIs differ from other API types (e.g., SOAP, GraphQL, or RPC-based APIs) in
several ways:

• Resource-Oriented: REST focuses on resources (e.g., /users/123) rather than

actions or procedures, unlike RPC APIs, which are operation-centric (e.g.,
getUser(123)).

• Use of HTTP Standards: REST leverages HTTP methods (GET, POST, PUT,
DELETE) and status codes (200, 404) directly, aligning with web standards,
whereas SOAP uses XML-based messaging over various protocols.

• Statelessness: Unlike session-based APIs (e.g., some SOAP implementations),

REST requires each request to be self-contained, enhancing scalability but
requiring more data in requests.

• Hypermedia (HATEOAS): REST APIs can include links in responses to guide

clients, a feature less common in other API types, making REST more dynamic
and discoverable.

• Flexibility in Data Formats: REST supports multiple formats (e.g., JSON, XML),
while SOAP is tied to XML, and GraphQL uses a specific query language.

• Simplicity and Scalability: REST’s reliance on HTTP and statelessness makes it

simpler and more scalable than SOAP, which has heavier XML overhead, or
GraphQL, which requires complex query resolution.

• Loose Coupling: REST’s uniform interface and HATEOAS reduce coupling

between client and server, unlike GraphQL, where clients tightly specify data
requirements.

Compared to SOAP, REST is lighter, more flexible, and web-native, avoiding complex
XML schemas and middleware. Compared to GraphQL, REST is simpler to implement
but less flexible for clients needing specific data structures, as GraphQL allows precise
querying. Compared to RPC, REST is more standardized and resource-focused,
avoiding proprietary operation definitions.

REST APIs are widely adopted due to their alignment with web architecture, ease of use,
and ability to scale, making them ideal for public APIs, mobile apps, and microservices.

REST API Design Rules

Below is the list of 37 design rules from the REST API Design Rulebook, organized by
chapter and section, with each rule accompanied by its description and page number
from the book.

Chapter 2: Identifier Design with URIs

This chapter provides rules for designing URIs to address resources consistently and
effectively.

1. Forward slash separator (/) must be used to indicate a hierarchical

relationship (Page 30)
The forward slash character is used in the URI path to indicate a hierarchical
relationship between resources.

2. A trailing forward slash (/) should not be included in URIs (Page 30)
Trailing slashes add no semantic value and may cause confusion, so they should
be avoided.

3. Hyphens (-) should be used to improve the readability of URIs (Page 30)
Hyphens enhance readability in long URI path segments, replacing spaces or
hyphens in English text.

4. Underscores (_) should not be used in URIs (Page 30)

Underscores can be obscured by underlining in text viewers, so hyphens are
preferred.

5. Lowercase letters should be preferred in URI paths (Page 31)

Lowercase letters are preferred to avoid confusion, as URIs are case-sensitive
except for scheme and host.

6. File extensions should not be included in URIs (Page 31)

File extensions (e.g., .json) should not be used to indicate format; media types
should be used instead.

7. Consistent subdomain names should be used for your APIs (Page 32)
APIs should use a consistent subdomain (e.g., api.soccer.restapi.org) to identify
the service owner.

8. Consistent subdomain names should be used for your client developer

portal (Page 32)
 Developer portals should use a consistent subdomain (e.g.,
developer.soccer.restapi.org).

9. A singular noun should be used for document names (Page 33)

Document resource names should use singular nouns (e.g., /league/seattle).

10. A plural noun should be used for collection names (Page 33)
Collection resource names should use plural nouns (e.g., /leagues).

11. A plural noun should be used for store names (Page 33)
Store resource names should use plural nouns (e.g., /favorites).

12. A verb or verb phrase should be used for controller names (Page 33)
Controller resource names should use verbs or verb phrases (e.g., /calculate).

13. Variable path segments may be substituted with identity-based values (Page
33)
URI path segments can include variable values based on resource identity (e.g.,
/users/{id}).

14. CRUD function names should not be used in URIs (Page 33)
URIs should not include CRUD operation names (e.g., avoid /getUser or
/deleteUser).

15. The query component of a URI may be used to filter collections or stores
(Page 33)
Query parameters can be used to filter resources in collections or stores (e.g.,
?name=John).

16. The query component of a URI should be used to paginate collection or store
results (Page 33)
Query parameters should support pagination (e.g., ?page=2&size=10).

Chapter 3: Interaction Design with HTTP

This chapter outlines rules for using HTTP methods and status codes appropriately in
REST API interactions.

17. GET and POST must not be used to tunnel other request methods (Page 34)
GET and POST should not be used to simulate other HTTP methods.

18. GET must be used to retrieve a representation of a resource (Page 34)

GET is for retrieving resource representations without side effects.

19. HEAD should be used to retrieve response headers (Page 34)

HEAD retrieves metadata (headers) without the resource body.
20. PUT must be used to both insert and update a stored resource (Page 34)
PUT is used for both creating and updating resources in a store.

21. PUT must be used to update mutable resources (Page 34)

PUT is for updating resources that can be modified.

22. POST must be used to create a new resource in a collection (Page 34)
POST creates new resources in server-managed collections.

23. POST must be used to execute controllers (Page 34)

POST is used to trigger controller actions.

24. DELETE must be used to remove a resource from its parent (Page 34)
DELETE removes a resource from its parent collection or store.

25. OPTIONS should be used to retrieve metadata that describes a resource’s

available interactions (Page 34)
OPTIONS provides metadata about a resource’s supported interactions.

26. 200 ("OK") should be used to indicate nonspecific success (Page 34)
200 indicates general success for a request.

27. 200 ("OK") must not be used to communicate errors in the response body
(Page 34)
Errors should use appropriate 4xx or 5xx codes, not 200 with error details.

28. 201 ("Created") must be used to indicate successful resource creation (Page
34)
201 indicates a resource was successfully created.

29. 202 ("Accepted") must be used to indicate successful start of an

asynchronous action (Page 35)
202 indicates an asynchronous operation has started.

30. 204 ("No Content") should be used when the response body is intentionally
empty (Page 35)
204 is used for successful requests with no response body.

31. 301 ("Moved Permanently") should be used to relocate resources (Page 35)
301 indicates a resource has been permanently moved to a new URI.

32. 302 ("Found") should not be used (Page 35)

Avoid 302 due to ambiguity; use 303 or 307 instead.

33. 303 ("See Other") should be used to refer the client to a different URI (Page
35)
303 directs clients to another URI for further action.
34. 304 ("Not Modified") should be used to preserve bandwidth (Page 35)
304 indicates the resource hasn’t changed since the last request.

35. 307 ("Temporary Redirect") should be used to tell clients to resubmit the
request to another URI (Page 35)
307 indicates a temporary redirect to another URI.

36. 400 ("Bad Request") may be used to indicate nonspecific failure (Page 35)
400 indicates a general client error.

37. 401 ("Unauthorized") must be used when there is a problem with the client’s
credentials (Page 35)
401 indicates invalid or missing credentials.