OpenAPI: REST API CRUD Users Endpoint

Building a Full CRUD Users API in OpenAPI

A CRUD API is the most common REST pattern. For a /users resource, you define five operations across two path patterns: the collection (/users) and the individual resource (/users/{id}).

Path Definitions

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
        '404':
          description: User not found

Key Design Decisions

• Collection vs. Resource paths: /users for listing and creating; /users/{id} for reading, updating, and deleting a specific user.
• OperationId: Each operation gets a unique ID (listUsers, createUser, getUserById, updateUser, deleteUser). These become function names in generated SDKs.
• Schema References: Use $ref to point to reusable schemas. Keep a User schema for responses and a UserInput schema for request bodies (which may omit auto-generated fields like id and createdAt).
• Status Codes: Return 200 for reads, 201 for creation, 204 for deletion, 400 for validation errors, and 404 when the resource is not found.

Response Schema

Define a User component with properties like id (string), name (string), email (string), and createdAt (string, format: date-time). Mark id, name, and email as required.