openapi.yaml

openapi: 3.0.3
info:
  title: TaskResolver API
  description: >
    Accepts a job (a list of shell tasks with optional `requires`
    dependencies), topologically sorts the tasks into a valid execution
    order, and returns either the sorted job as JSON or as an executable
    bash script.

    **Content negotiation:** In Swagger UI, pick the desired representation
    from the **Response content type** dropdown on the `200` response. That
    sets the `Accept` header automatically (`application/json`, `text/plain`,
    or `text/x-shellscript`). When `Accept` is omitted, the API defaults to
    `application/json`.
  version: "1.0.0"
servers:
  - url: http://localhost:4000
    description: Local development server

paths:
  /health:
    get:
      summary: Liveness check
      operationId: getHealth
      responses:
        "200":
          description: The service is up.
          content:
            text/plain:
              schema:
                type: string
                example: ok

  /resolve:
    post:
      summary: Sort a job's tasks into a valid execution order
      operationId: resolveJob
      description: >
        Validates the job payload, topologically sorts its tasks, and returns
        the result in the representation selected via the `Accept` header (see
        the `200` response content types below).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Job"
            example:
              tasks:
                - name: task-1
                  command: touch /tmp/file1
                - name: task-2
                  command: cat /tmp/file1
                  requires: [task-3]
                - name: task-3
                  command: echo 'Hello World!' > /tmp/file1
                  requires: [task-1]
                - name: task-4
                  command: rm /tmp/file1
                  requires: [task-2, task-3]
      responses:
        "200":
          description: The job was validated and its tasks sorted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResult"
              example:
                tasks:
                  - name: task-1
                    command: touch /tmp/file1
                  - name: task-3
                    command: echo 'Hello World!' > /tmp/file1
                  - name: task-2
                    command: cat /tmp/file1
                  - name: task-4
                    command: rm /tmp/file1
            text/plain:
              schema:
                type: string
                description: Executable bash script with commands in sorted order.
                example: |
                  #!/usr/bin/env bash
                  touch /tmp/file1
                  echo 'Hello World!' > /tmp/file1
                  cat /tmp/file1
                  rm /tmp/file1
            text/x-shellscript:
              schema:
                type: string
                description: Executable bash script with commands in sorted order.
                example: |
                  #!/usr/bin/env bash
                  touch /tmp/file1
                  echo 'Hello World!' > /tmp/file1
                  cat /tmp/file1
                  rm /tmp/file1
        "400":
          description: The request body is not syntactically valid JSON.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: bad_request
                message: the request body is not valid JSON
        "406":
          description: The `Accept` header requests an unsupported representation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: not_acceptable
                message: "Accept header must be one of: application/json, text/plain, text/x-shellscript"
        "415":
          description: The `Content-Type` header is missing or is not `application/json`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: unsupported_media_type
                message: Content-Type must be application/json
        "422":
          description: >
            The job failed contract validation, or its tasks could not be
            sorted due to a duplicate task name, a missing dependency, or a
            cyclic dependency.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                contract_validation:
                  summary: Contract validation failure
                  value:
                    error: invalid_job
                    message: the job payload failed contract validation
                    details:
                      tasks:
                        - command: ["can't be blank"]
                missing_dependency:
                  summary: Dependency on an undefined task
                  value:
                    error: missing_dependency
                    message: 'a task requires "ghost", which is not defined in this job'
                    details:
                      name: ghost
                cyclic_dependency:
                  summary: Cyclic dependency between tasks
                  value:
                    error: cyclic_dependency
                    message: "cyclic dependency detected among tasks: a -> b -> a"
                    details:
                      tasks: [a, b, a]

components:
  schemas:
    Task:
      type: object
      required: [name, command]
      properties:
        name:
          type: string
          description: Unique identifier for this task within the job.
          example: task-1
        command:
          type: string
          description: Shell command to execute for this task.
          example: touch /tmp/file1
        requires:
          type: array
          description: Names of tasks that must run before this one.
          items:
            type: string
          default: []
          example: [task-2, task-3]

    Job:
      type: object
      required: [tasks]
      properties:
        tasks:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/Task"

    TaskOutput:
      type: object
      description: >
        A task in the sorted JSON response. Only `name` and `command` are
        returned; the `requires` field from the request is intentionally
        omitted.
      required: [name, command]
      additionalProperties: false
      properties:
        name:
          type: string
          description: Unique identifier for this task within the job.
          example: task-1
        command:
          type: string
          description: Shell command to execute for this task.
          example: touch /tmp/file1

    JobResult:
      type: object
      description: >
        Sorted job returned when `Accept` is `application/json` (or omitted).
        Matches the Elixir response shape: an object with a `tasks` array of
        `TaskOutput` objects (no `requires` field).
      required: [tasks]
      properties:
        tasks:
          type: array
          description: Tasks in a valid execution order.
          items:
            $ref: "#/components/schemas/TaskOutput"

    Error:
      type: object
      required: [error, message]
      properties:
        error:
          type: string
          description: Machine-readable error code.
          enum:
            - bad_request
            - not_acceptable
            - unsupported_media_type
            - invalid_job
            - duplicate_task
            - missing_dependency
            - cyclic_dependency
            - not_found
            - payload_too_large
        message:
          type: string
          description: Human-readable description of the error.
        details:
          description: >
            Optional structured detail. Present for `422` responses; shape
            depends on the `error` code (field errors for `invalid_job`,
            task name for `missing_dependency`, task list for
            `cyclic_dependency`).