---
openapi: 3.0.1
info:
  title: Jobq
  description: A trivial job queue API

tags:
  - name: queue
  - name: job

definitions:
  parameters:
    q_id:
      in: path
      name: q_id
      required: true
      description: The ID of a given queue
      schema:
        $ref: "#/definitions/types/id"

    j_id:
      in: path
      name: j_id
      required: true
      description: The ID of a given job
      schema:
        $ref: "#/definitions/types/id"

  responses:
    job: {}

    jobs:
      "200":
        description: A list of jobs
        content:
          application/json:
            schema:
              $ref: "#/definitions/types/jobs"

  types:
    id:
      type: int

    job:
      type: object
      properties:
        id:
          $ref: "#/definitions/types/id"
        payload: {}
        events: {}
        state: {}
        modified:
          type: int

paths:
  "/api/v0/job":
    get:
      description: "Query the jobs in a queue."
      parameters:
        - $ref: "#/definitions/parameters/q_id"

    post:
      description: "Query the jobs in a queue."
      parameters:
        - $ref: "#/definitions/parameters/q_id"

      responses:
        "200": {}

  "/api/v0/job/create":
    post:
      description: "Create a job within a given queue."
      parameters:
        - $ref: "#/definitions/parameters/q_id"


  "/api/v0/job/poll":
    post:
      description: "Poll zero or one jobs off the queue."
      parameters:
        - $ref: "#/definitions/parameters/q_id"

  "/api/v0/job/{j_id}":
    get:
      description: "Return all available data about the job"
      parameters:
        - $ref: "#/definitions/parameters/j_id"

    delete:
      description: "Expunge the job"
      parameters:
        - $ref: "#/definitions/parameters/j_id"

  "/api/v0/job/{j_id}/state":
    post:
      description: "Alter the job's state, appending an event"
      parameters:
        - $ref: "#/definitions/parameters/j_id"

  "/api/v0/job/{j_id}/event":
    post:
      description: "Append an event to a given job without modifying state"
      parameters:
        - $ref: "#/definitions/parameters/j_d"
