[ADP-301] Resource-Oriented Design

reviewing phase 1

Needs more reference

Overview

Resource-oriented design is a fundamental approach in REST API development that builds the API structure around resources, which are the key abstractions of information or services provided by the API.

Guidance

• API designers MUST identify and clearly define the resources that their API will expose.
• Resources SHOULD be represented by unique and logical URIs.
• API implementations MUST use appropriate HTTP methods (GET, POST, PUT, DELETE, etc.) to perform operations on resources.

  TIP

  See ADP-110: HTTP Methods.

• Resource representations SHOULD use standard formats (including JSON or XML), with this API design principle specifying the use of JSON.
• API interactions MUST be stateless, with each request containing all necessary information.

  TIP

  Long-running tasks can be considered a compliant exception; see ADP-357: Long-Running Tasks.

• API designers SHOULD use nouns rather than verbs in resource URIs.

  TIP

  When designing POST + action-related endpoints, treat them as nouns; refer to ADP-302: URL Design Principles.

• API implementations MUST implement correct HTTP status codes.
• API designers SHOULD provide clear and consistent naming conventions.
• Collection resources SHOULD use plural nouns.
• API implementations MUST implement appropriate error handling and messaging.
• API designers MAY consider versioning their API to manage changes over time.

What is a Resource?

In the context of REST APIs, a resource is any named information or service that can be identified, named, addressed, or acted upon over the network. Resources can be individual entities (e.g., a specific user) or collections (e.g., all users). They are the fundamental concept of REST API operations.

What is Not Resource-Oriented API Design?

To better understand resource-oriented design, it is helpful to recognize approaches that do not conform to this principle:

1. Action-Centric API Design:

   • Examples: /getUser, /createPost, /deleteComment
   • These designs include actions in the URI rather than using HTTP methods to represent actions.

2. RPC-Style APIs:

   • Examples: /api/doSomething, /api/processData
   • These designs resemble remote procedure calls rather than operations on resources.

3. Single Endpoint APIs:

   • Example: /api (all operations are performed through this single endpoint, distinguished by parameters)
   • This design lacks a clear resource concept, mixing all operations together.

These non-resource-oriented API designs often lead to APIs that are harder to understand, use, and maintain, and are not conducive to the expansion and evolution of the API.

Examples

Consider a simple blog API:

1. Resources:

   • Posts
   • Comments
   • Users

2. URI Design:

   • /posts (collection of all posts)
   • /posts/{id} (specific post)
   • /posts/{id}/comments (comments for a specific post)
   • /users (collection of all users)
   • /users/{id} (specific user)

3. HTTP Methods:

   • GET /posts - Retrieve all posts
   • POST /posts - Create a new post
   • PUT /posts/{id} - Update a specific post
   • DELETE /posts/{id} - Delete a specific post