ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-300] REST Overview ​

reviewing phase 1

Link to every ADP.

INFO

This ADP provides an overview of REST (Representational State Transfer) principles and best practices for API design.

ADP Numbering scope: 300-349

Our Approach to REST ​

We adopt a Pragmatic RESTful approach rather than strictly adhering to Roy T. Fielding's original REST definition or fully following the Richardson Maturity Model (RMM, Richardson Maturity Model, because I think there's gap between RMM level 2 and 3). This practical approach:

  • Focuses on real-world implementation needs over academic purity
  • Does not blindly pursue HATEOAS (Hypermedia as the Engine of Application State) when it adds unnecessary complexity
  • Extends beyond RMM by leveraging both existing and emerging HTTP RFC capabilities
  • Prioritizes developer experience and API usability

This pragmatic stance allows us to create APIs that are both RESTful in spirit and practical in implementation, balancing theoretical correctness with real-world requirements.

Key Concepts ​

Resources ​

REST is centered around resources, which are any entities that can be identified, named, addressed, or handled in the system. Resources are typically nouns and should be named using clear, descriptive terms.

Representations ​

Resources can have multiple representations, such as JSON, XML, or HTML. The representation format is typically specified using the Content-Type header.

HTTP Methods ​

RESTful APIs use standard HTTP methods to perform operations on resources:

  • GET: Retrieve a resource
  • POST: Create a new resource
  • PUT: Update an existing resource
  • DELETE: Remove a resource
  • PATCH: Partially modify a resource

Please refer ADP-110: HTTP Methods for further info.

Statelessness ​

Each request from a client to the server must contain all the information needed to understand and process the request. The server should not store any client context between requests.

Best Practices ​

When designing RESTful APIs:

  • Use nouns, not verbs, in endpoint paths
  • Use plural nouns for consistency (e.g., /users instead of /user)
  • Use HTTP methods appropriately for CRUD operations
  • Use proper HTTP status codes to indicate the outcome of requests
  • Implement proper error handling and provide meaningful error messages
  • Use query parameters for filtering, sorting, and pagination
  • Version your API to maintain backward compatibility

These principles would be mentioned in below ADPs.

References ​