Designing CRUD Endpoints in OpenAPI

CRUD Endpoints in OpenAPI

CRUD (Create, Read, Update, Delete) is the foundation of REST API design. OpenAPI provides a structured way to define all four operations with proper HTTP methods, status codes, and schemas.

The Standard CRUD Pattern

paths:
  /resources:
    get:
      summary: List resources
      responses:
        "200":
          description: Success
    post:
      summary: Create a resource
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResource"
      responses:
        "201":
          description: Created

  /resources/{id}:
    get:
      summary: Get a resource
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
        "404":
          description: Not found
    put:
      summary: Update a resource
      responses:
        "200":
          description: Updated
    delete:
      summary: Delete a resource
      responses:
        "204":
          description: Deleted

HTTP Methods Mapping

Operation	HTTP Method	Collection Path	Item Path
Create	POST	/resources	-
Read (list)	GET	/resources	-
Read (single)	GET	-	/resources/{id}
Update (full)	PUT	-	/resources/{id}
Update (partial)	PATCH	-	/resources/{id}
Delete	DELETE	-	/resources/{id}

Response Status Codes

Each operation should return appropriate status codes:

• GET (list): 200 OK with array body
• GET (single): 200 OK or 404 Not Found
• POST: 201 Created with Location header
• PUT/PATCH: 200 OK with updated resource
• DELETE: 204 No Content (empty body)

Request and Response Schemas

Define separate schemas for creation, update, and response:

components:
  schemas:
    CreateResource:
      type: object
      required: [name]
      properties:
        name:
          type: string
    UpdateResource:
      type: object
      properties:
        name:
          type: string
    Resource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time

Using separate schemas prevents clients from setting server-generated fields like id and created_at during creation.