treeman-openapi-v1.yaml

---
openapi: "3.1.0"
info:
  version: 0.0.1
  title: Treeman
  description: Treeman is a manager for directory trees.
  contact:
    name: Infratographer Authors
    url: http://github.com/infratographer
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
#servers:
#  - url: http://localhost/api/v1
paths:
  /roots:
    get:
      description: |
        Returns a list of root directories.
      operationId: listRoots
      parameters:
        - $ref: '#/components/parameters/with_deleted'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: directories response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DirectoryList'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      description: Creates a new root directory
      operationId: createRootDirectory
      requestBody:
        description: New root directory to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectoryRequest'
      responses:
        '201':
          description: directory response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryFetch'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /directories/{id}:
    get:
      description: Returns a directory based on a single ID.
      operationId: getDirectory
      parameters:
        - name: id
          in: path
          description: ID of directory to return
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
        - $ref: '#/components/parameters/with_deleted'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: directory response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryFetch'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      description: Creates a new sub-directory given the ID of the parent directory
      operationId: createDirectory
      parameters:
        - name: id
          in: path
          description: ID of the parent directory to create a sub-directory in
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
      requestBody:
        description: New directory to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectoryRequest'
      responses:
        '201':
          description: directory response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryFetch'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      description: Updates the given directory for the provided ID
      operationId: updateDirectory
      parameters:
        - name: id
          in: path
          description: ID of the directory to update
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
      requestBody:
        description: Fields to update for the directory
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDirectoryRequest'
      responses:
        '201':
          description: directory response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryFetch'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    # TODO: Implement this
    # put:
    
    delete:
      description: Deletes a directory and all of its children.
      operationId: deleteDirectory
      parameters:
        - name: id
          in: path
          description: ID of directory to delete
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
      responses:
        '200':
          description: affected directories response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryList'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /directories/{id}/children:
    get:
      description: Returns a list of child directories for a given directory ID.
      operationId: listChildren
      parameters:
        - name: id
          in: path
          description: ID of directory to return children for
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
        - $ref: '#/components/parameters/with_deleted'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: directories response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryList'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /directories/{id}/parents:
    get:
      description: Returns a list of parent directories for a given directory ID.
      operationId: listParents
      parameters:
        - name: id
          in: path
          description: ID of directory to return parents for
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
        - $ref: '#/components/parameters/with_deleted'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: directories response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryList'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /directories/{id}/parents/{until}:
    get:
      description: Returns a list of parent directories for a given directory ID until a given directory ID.
      operationId: listParentsUntil
      parameters:
        - name: id
          in: path
          description: ID of directory to return parents for
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
        - name: until
          in: path
          description: ID of directory to stop returning parents at
          required: true
          schema:
            type: string
            x-go-type: DirectoryID
        - $ref: '#/components/parameters/with_deleted'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: directories response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryList'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Directory:
      allOf:
        - $ref: '#/components/schemas/NewDirectory'
        - type: object
          required:
          - id
          - createdAt
          - updatedAt
          properties:
            id:
              type: string
              x-go-type: DirectoryID
            parent:
              type: string
              x-go-type: DirectoryID
              optional: true
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            deletedAt:
              type: string
              format: date-time

    NewDirectory:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          x-oapi-codegen-extra-tags:
            binding: required
        metadata:
          type: object
          x-go-type: DirectoryMetadata
    
    Pagination:
      allOf:
        - type: object
          required:
            - page
            - page_size
          properties:
            page:
              type: integer
              default: 1
            page_size:
              type: integer
              default: 10
        - type: object
          required:
            - _links
          properties:
            _links:
              $ref: '#/components/schemas/PaginationLinks'

    PaginationLinks:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/Link'
    
    Link:
      type: object
      x-omitempty: false
      required:
        - href
      properties:
        href:
          type: string
          x-go-name: HREF

    DirectoryRequestMeta:
      type: object
      required:
        - version
      properties:
        version:
          type: string

    CreateDirectoryRequest:
      allOf:
        - $ref: '#/components/schemas/DirectoryRequestMeta'
        - $ref: '#/components/schemas/NewDirectory'

    UpdateDirectoryRequest:
      allOf:
        - $ref: '#/components/schemas/DirectoryRequestMeta'
        - type: object
          properties:
            name:
              type: string
            metadata:
              type: object
              x-go-type: DirectoryMetadata

    # Response for fetching directories
    DirectoryFetch:
      allOf:
        - $ref: '#/components/schemas/DirectoryRequestMeta'
        - type: object
          required:
            - directory
          properties:
            directory:
              $ref: '#/components/schemas/Directory'

    # Response for listing directories
    DirectoryList:
      allOf:
        - $ref: '#/components/schemas/DirectoryRequestMeta'
        - type: object
          required:
            - directories
          properties:
            directories:
              type: array
              items:
                type: string
                x-go-type: DirectoryID
        - $ref: '#/components/schemas/Pagination'

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

  parameters:
    with_deleted:
      in: query
      name: with_deleted
      required: false
      schema:
        type: boolean
        default: false
    page:
      in: query
      name: page
      required: false
      schema:
        type: integer
        default: 0
    limit:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        default: 0