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

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 ​