OpenAPI: REST API CRUD Orders Endpoint

Defining an Orders CRUD API

An orders API introduces concepts not found in simple CRUD: nested resources (line items), status state machines, and computed fields (totals).

Order Schema with Nested Items

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - customerId
        - items
        - status
      properties:
        id:
          type: string
        customerId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        status:
          type: string
          enum:
            - pending
            - confirmed
            - shipped
            - delivered
            - cancelled
        totalAmount:
          type: number
        createdAt:
          type: string
    LineItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
        quantity:
          type: integer
        unitPrice:
          type: number

Status Transitions via PATCH

Rather than allowing full PUT updates on orders, use PATCH to update specific fields like status:

/orders/{id}/status:
  patch:
    summary: Update order status
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - status
            properties:
              status:
                type: string
                enum:
                  - confirmed
                  - shipped
                  - delivered
                  - cancelled
    responses:
      '200':
        description: Status updated
      '400':
        description: Invalid status transition

Design Considerations

• Enum for status: Using enum in OpenAPI documents the valid status values and enables code generators to create type-safe status handling.
• Computed fields: totalAmount is calculated from line items and should be read-only. Mark it with readOnly: true in OpenAPI 3.0.
• Nested creation: When creating an order, the items array is submitted in the request body. The server resolves product prices and computes the total.