Skip to main content

Requirements

API version: 1.0.0

Source​

Users API details (OpenAPI specification)
openapi: 3.0.3
info:
  title: Users Management API
  description: API for managing users in an application.
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserCreate"
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string

    get:
      summary: Get a user by ID
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found

    put:
      summary: Update a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdate"
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found

    delete:
      summary: Delete a user
      responses:
        "204":
          description: User deleted
        "404":
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "123"
        name:
          type: string
          example: "Username"
        email:
          type: string
          format: email
          example: "username@example.com"

    UserCreate:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

    UserUpdate:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email

Specification analysis (Static testing)​

Observations:

The following behaviors are not completely defined by the current OpenAPI specification:

  • Minimum and maximum length for name.
  • Minimum and maximum length for email.
  • Whether an empty name is allowed.
  • Whether an empty UserUpdate object is allowed.
  • Expected status code and error format for validation errors.
  • Expected behavior for malformed or empty path parameters.
  • Whether duplicate email addresses are allowed.
  • Authentication and authorization requirements.
  • Pagination/filtering requirements for GET /users.

Requirements to clarified​

REQ-USER-001 — User name length​

Expectations:
The user name must have a defined minimum and maximum length.

Status: Undefined

REQ-USER-002 — Duplicated email​

Expectations:
The API must define whether duplicate email addresses are allowed.

Status: Undefined