The CRUD pattern outlines the design and implementation of Create, Read, Update, and Delete (CRUD) operations in REST-based APIs, providing a standard approach to managing resources in a web service.

Details

CRUD operations form the backbone of most web APIs, enabling clients to interact with and manage server-side resources. Each operation corresponds to a standard HTTP method:

  • POST for creating a new resource instance within a resource collection
  • GET for reading an existing resource instance or listing/filtering a resource collection
  • PUT or PATCH for updating a resource instance or resource collection
  • DELETE for deleting resource instances or entire collections

This pattern ensures consistency, predictability, and usability across different platforms and technologies, making it a foundational aspect of RESTful API design.

Common Pattern Names/Synonyms

  • Basic CRUD Operations
  • RESTful CRUD Pattern
  • CRUD Lifecycle Management
  • CRUD Interface Pattern

Common Use Cases

  1. User Management: Creating user accounts, retrieving user information, updating user details, and deleting users.
  2. Product Catalog: Managing entries of products including addition, retrieval, modification, and removal.
  3. Order Processing: Handling orders where each step involves creating, viewing, modifying, or cancelling orders.

When to Use

  • Resource management needs: Ideal for any application requiring basic management of data entities with a standard CRUD lifecycle.
  • Standardization across services: Useful for services needing a uniform interface that developers can quickly understand and use.
  • Building foundational services: Essential for initial API setups where basic data operations are needed.

When Not to Use

  • Non-resource-based interactions: Not suitable for operations that don’t neatly map onto resource manipulation (e.g., complex transactions or multi-step processes that require maintaining state between calls).
  • Optimization required for specific operations: In cases where operations need to be highly optimized and diverge from standard CRUD operations, such as bulk updates or specialized transaction control.

Examples

Create a New Resource

Request:

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john.doe@example.com"
}

Response:

HTTP/1.1 201 Created
Location: /api/users/123

Read an Existing Resource

Request:

GET /api/users/123 HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "123",
  "name": "John Doe",
  "email": "john.doe@example.com"
}

Update an Existing Resource

Request:

PUT /api/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Johnny Doe",
  "email": "johnny.doe@example.com"
}

Response:

HTTP/1.1 200 OK

Delete an Existing Resource

Request:

DELETE /api/users/123 HTTP/1.1
Host: example.com

Response:

HTTP/1.1 204 No Content

List Resources

Request:

GET /api/users HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
 {
   "id": "123",
   "name": "John Doe",
   "email": "john.doe@example.com"
 }, 
 ...
]

Sequence Diagram

sequenceDiagram
    participant Client
    participant Server
    participant Database

    Note over Client,Server: CRUD Operations

    Client->>Server: POST /users (Create User)
    Server->>Database: Insert User Data
    Database-->>Server: Confirmation
    Server-->>Client: 201 Created (Location Header)

    Client->>Server: GET /users/{userId} (Read User)
    Server->>Database: Fetch User Data
    Database-->>Server: User Data
    Server-->>Client: 200 OK (User Data)

    Client->>Server: GET /users/ (List Users)
    Server->>Database: Fetch Users Data
    Database-->>Server: Users Data
    Server-->>Client: 200 OK (Users Data)

    Client->>Server: PUT /users/{userId} (Update User)
    Server->>Database: Update User Data
    Database-->>Server: Update Confirmation
    Server-->>Client: 200 OK

    Client->>Server: DELETE /users/{userId} (Delete User)
    Server->>Database: Delete User Data
    Database-->>Server: Deletion Confirmation
    Server-->>Client: 204 No Content

OpenAPI Example

openapi: 3.0.0
info:
  title: CRUD API
  version: 1.0.0
servers:
  - url: 'https://api.example.com'
paths:
  /users/{userId}:
    get:
      summary: Retrieves a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                user:
                  value:
                    id: "123"
                    name: "John Doe"
                    email: "john.doe@example.com"
    put:
      summary: Updates a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            examples:
              updatedUser:
                value:
                  name: "Johnny Doe"
                  email: "johnny.doe@example.com"
      responses:
        '200':
          description: Successfully updated
    delete:
      summary: Deletes a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successfully deleted
  /users:
    post:
      summary: Creates a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            examples:
              newUser:
                value:
                  name: "John Doe"
                  email: "john.doe@example.com"
      responses:
        '201':
          description: User created
          headers:
            Location:
              schema:
                type: string
              description: URI of the created user
    get:
      summary: Retrieves a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                users:
                  value:
                    - id: "123"
                      name: "John Doe"
                      email: "john.doe@example.com"
                    - id: "124"
                      name: "Jane Doe"
                      email: "jane.doe@example.com"
components:
  schemas:
    User:
      type: object
      required:
        - name
        - email
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

Updated: