Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
457 lines (428 sloc) 11.9 KB
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.
You can’t perform that action at this time.