api-specification.yml

swagger: '2.0'
info:
  description: |
    Official documentation for BugZoo's RESTful API.
  version: '1.0'
  title: BugZoo - API Specification
  contact:
    name: Christopher Timperley
    url: https://github.com/squaresLab/BugZoo
host: localhost
basePath: /bugzoo


tags:
  - name: container
    description: All operations related to containers
  - name: bug
    description: All operations related to bugs
  - name: docker
    description: All operations related to the underlying Docker installation
  - name: configuration
    description: All operations related to the server configuration


definitions:
  Bug:
    type: object
    required:
      - id
    properties:
      id:
        type: string
        description: A unique identifier for this bug.
        example: 'manybugs:python:69223-69224'

  Container:
    type: object
    required:
      - id
    properties:
      id:
        type: string
        description: >-
          A unique identifier for the container. If an ID was not provided by
          the user upon the creation of the container, an ID will automatically
          be generated instead.

  ExecResponse:
    type: object
    required:
      - code
      - duration
      - output
    properties:
      code:
        type: number
        format: int
        description: >-
          The exit code produced by the command.
      duration:
        type: number
        format: float
        description: >-
          The number of seconds taken to execute the command.
      output:
        type: string
        description: >-
          The output produced by the command.


paths:
###############################################################################
# Configuration
###############################################################################

  /status:
    get:
      summary: Status of the server.
      description: >-
        Produces a diagnostic summary of the health of the server.
      tags:
        - configuration
      produces:
        - application/json
      responses:
        204:
          description: Server is running.

###############################################################################
# Docker
###############################################################################

  /docker/images/${name}:
    delete:
      summary: Destroys a given Docker image.
      description: Destroys a given Docker image.
      parameters:
        - in: path
          name: name
          type: string
          description: The name of the Docker image.
          required: true
      tags:
        - docker
      responses:
        204:
          description: Docker image was successfully destroyed.
        404:
          description: Docker image was not found or has already been destroyed.

###############################################################################
# Bugs
###############################################################################

  /bugs:
    get:
      summary: List of registered bugs.
      description: >-
        Produces a list of all the bugs registered with this server given by
        their unique identifiers.
      tags:
        - bug
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: string
              description: The unique identifier of the bug.
              example: 'manybugs:python:69223-69224'

  /bugs/${id}:
    get:
      summary: Bug information.
      description: Produces a detailed description of a given bug.
      tags:
        - bug
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the bug.
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Bug'
        404:
          description: Bug not found.

    put:
      summary: Registers a bug with the server.
      description: Registers a given bug with this server.
      tags:
        - bug
      consumes:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the bug.
          required: true
        - in: body
          name: Parameters
          required: true
          schema:
            $ref: '#/definitions/Bug'
      responses:
        204:
          description: The bug was successfully registered.
        400:
          description: The bug description is invalid.

  /bugs/${id}/build:
    post:
      summary: Builds the Docker image for a bug from its blueprint.
      description: Builds the Docker image for a given bug.
      tags:
        - bug
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the bug.
          required: true
      responses:
        204:
          description: Built bug.
        200:
          description: Bug already built.
        404:
          description: Bug not found.

  /bugs/${id}/download:
    post:
      summary: Downloads the Docker image for a bug.
      description: Downloads the Docker image for a bug from DockerHub.
      tags:
        - bug
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the bug.
          required: true
      responses:
        204:
          description: Successfully downloaded Docker image.
        200:
          description: Docker image already installed.
        404:
          description: Bug not found.


###############################################################################
#
# Containers
#
###############################################################################

  /containers:
    get:
      summary: List of running containers.
      description: >-
        Produces a list of the names of all of the containers that are
        currently running on this server.
      tags:
        - container
      produces:
        - application/json
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Container'
        404:
          description: Bug not found.

  /containers/${id}:
    get:
      summary: Container information.
      description: Produces a detailed description of a given container.
      tags:
        - container
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the container.
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Container'
        404:
          description: Container not found.

    patch:
      summary: Patches source code inside container.
      description: >-
        Attempts to apply a given patch to the source code for the program
        inside the container.
      tags:
        - container
      consumes:
        - text/plain
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the container.
          required: true
        - in: body
          name: patch
          type: string
          required: true
          description: >-
            The patch that should be applied to the source code, given as a
            unified diff.
      responses:
        204:
          description: OK.
        400:
          description: Failed to apply patch.

    delete:
      summary: Destroy container.
      description: Destroys a given container.
      tags:
        - container
      produces:
        - application/json
      parameters:
      - in: path
        name: id
        type: string
        description: The unique identifier of the container.
        required: true
      responses:
        204:
          description: OK
        404:
          description: Container does not exist or was already destroyed.

  /containers/${container-id}/test/${test-id}:
    post:
      summary: Executes a test inside a container.
      description: >-
        Executes a test case belonging to the program within a given container,
        and returns the outcome of the execution.
      tags:
        - container
      produces:
        - application/json
      parameters:
        - in: path
          name: container-id
          type: string
          description: The unique identifier of the container.
          required: true
        - in: path
          name: test-id
          type: string
          description: The unique identifier of the test case.
          required: true
      responses:
        200:
          description: OK
          schema:
            type: object
        404:
          description: Container or test case not found.

  /containers/${container-id}/compile:
    post:
      summary: Compiles program inside container.
      description: >-
        Attempts to compile the program inside a given container, and returns
        a description of the outcome of the compilation process.
      tags:
        - container
      produces:
        - application/json
      parameters:
        - in: path
          name: container-id
          type: string
          description: The unique identifier of the container.
          required: true
      responses:
        200:
          description: Compilation success.
        211:
          description: Compilation failure.
        212:
          description: Compilation timeout.
        404:
          description: Container not found.

  /containers/${id}/persist/${image}:
    post:
      summary: Persists container to a Docker image.
      description: >-
        Persists the state of a container to a Docker image on the server.
      tags:
        - container
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the container.
          required: true
        - in: path
          name: image
          type: string
          required: true
          description: >-
            The name of the Docker image to which the state of the container
            should be persisted.
      responses:
        204:
          description: The container was persisted as a Docker image.
        400:
          description: >-
            An error occurred whilst attempting to persist the container.
        404:
          description: Container not found.
        409:
          description: There already exists a Docker image with the given name.

  /containers/${id}/exec:
    post:
      summary: Executes a command inside the container.
      description: >-
        Executes a given command inside the container.
      tags:
        - container
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          type: string
          description: The unique identifier of the container.
          required: true
      responses:
        200:
          description: OK.
          schema:
            $ref: '#/definitions/ExecResponse'
        404:
          description: Container not found.

  /containers/${container-id}/alive:
    get:
      summary: Checks whether container is alive.
      description: >-
        Checks whether the underlying Docker container for a given BugZoo
        container is alive.
      tags:
        - container
      produces:
        - application/json
      parameters:
        - in: path
          name: container-id
          type: string
          description: The unique identifier of the container.
          required: true
      responses:
        200:
          description: OK
          schema:
            type: boolean
            description: >-
              A flag indicating whether or not the container is alive.
        404:
          description: Container not found.