openapi.yaml

openapi: 3.0.3
info:
  title: Notes API
  description: A simple CRUD REST API for managing notes with pagination, filtering, and sorting capabilities.
  version: "1.0.0"
  contact:
    name: API Support
    email: support@notesapi.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080
    description: Local development server

paths:
  /healthz:
    get:
      summary: Health check endpoint
      description: Returns the health status of the API
      operationId: getHealth
      tags:
        - Health
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /v1/notes:
    get:
      summary: List notes
      description: Retrieve a paginated list of notes with optional filtering and sorting
      operationId: listNotes
      tags:
        - Notes
      parameters:
        - name: page
          in: query
          description: Page number (starts from 1)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: q
          in: query
          description: Search query to filter notes by title or content
          required: false
          schema:
            type: string
            maxLength: 200
        - name: tags
          in: query
          description: Filter by tags (can specify multiple)
          required: false
          schema:
            type: array
            items:
              type: string
              maxLength: 50
            maxItems: 10
        - name: sort
          in: query
          description: Sort field
          required: false
          schema:
            type: string
            enum: [created_at, updated_at]
            default: created_at
        - name: order
          in: query
          description: Sort order
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: List of notes with pagination metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    post:
      summary: Create a new note
      description: Create a new note with title, content, and optional tags
      operationId: createNote
      tags:
        - Notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNoteRequest'
      responses:
        '201':
          description: Note created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/notes/{id}:
    get:
      summary: Get a note by ID
      description: Retrieve a specific note by its UUID
      operationId: getNote
      tags:
        - Notes
      parameters:
        - name: id
          in: path
          description: Note UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Note details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Invalid note ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    patch:
      summary: Update a note
      description: Partially update a note's fields
      operationId: updateNote
      tags:
        - Notes
      parameters:
        - name: id
          in: path
          description: Note UUID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNoteRequest'
      responses:
        '200':
          description: Note updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Delete a note
      description: Delete a note by its UUID (idempotent operation)
      operationId: deleteNote
      tags:
        - Notes
      parameters:
        - name: id
          in: path
          description: Note UUID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Note deleted successfully
        '400':
          description: Invalid note ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    Note:
      type: object
      required:
        - id
        - title
        - content
        - tags
        - is_archived
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the note
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Note title
        content:
          type: string
          maxLength: 10000
          description: Note content
        tags:
          type: array
          items:
            type: string
            maxLength: 50
          maxItems: 10
          description: List of tags associated with the note
        is_archived:
          type: boolean
          description: Whether the note is archived
        created_at:
          type: string
          format: date-time
          description: Timestamp when the note was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the note was last updated

    CreateNoteRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Note title
        content:
          type: string
          maxLength: 10000
          description: Note content
          default: ""
        tags:
          type: array
          items:
            type: string
            maxLength: 50
          maxItems: 10
          description: List of tags for the note
        is_archived:
          type: boolean
          description: Whether the note should be archived
          default: false

    UpdateNoteRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: Updated note title
        content:
          type: string
          maxLength: 10000
          description: Updated note content
        tags:
          type: array
          items:
            type: string
            maxLength: 50
          maxItems: 10
          description: Updated list of tags
        is_archived:
          type: boolean
          description: Updated archive status

    ListNotesResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: Array of notes
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'

    PaginationMetadata:
      type: object
      required:
        - page
        - page_size
        - total
      properties:
        page:
          type: integer
          description: Current page number
        page_size:
          type: integer
          description: Number of items per page
        total:
          type: integer
          description: Total number of items
        next_page:
          type: integer
          nullable: true
          description: Next page number if available

    HealthResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum: [ok]
          description: Health status

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'

    ErrorDetail:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum: [VALIDATION_ERROR, NOT_FOUND, INTERNAL_ERROR]
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true

  responses:
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "VALIDATION_ERROR"
              message: "Invalid input parameters"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "NOT_FOUND"
              message: "Resource not found"

    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: "INTERNAL_ERROR"
              message: "Internal server error"

tags:
  - name: Health
    description: Health check operations
  - name: Notes
    description: Notes CRUD operations