869 lines
20 KiB
YAML
869 lines
20 KiB
YAML
swagger: "2.0"
|
|
info:
|
|
version: 1.0.0
|
|
title: Drone API
|
|
license:
|
|
name: Creative Commons 4.0 International
|
|
url: "http://creativecommons.org/licenses/by/4.0/"
|
|
|
|
host: "localhost:8080"
|
|
basePath: /api
|
|
schemes:
|
|
- http
|
|
- https
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
|
|
#
|
|
# Operation tags
|
|
#
|
|
|
|
tags:
|
|
- name: Repos
|
|
- name: Builds
|
|
- name: User
|
|
- name: Users
|
|
|
|
#
|
|
# Security Definitions
|
|
#
|
|
|
|
security:
|
|
- accessToken: []
|
|
securityDefinitions:
|
|
accessToken:
|
|
type: apiKey
|
|
in: query
|
|
name: access_token
|
|
|
|
#
|
|
# Endpoint Definitions
|
|
#
|
|
|
|
paths:
|
|
|
|
#
|
|
# Repos Endpoint
|
|
#
|
|
|
|
/repos/{owner}/{name}:
|
|
get:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
tags:
|
|
- Repos
|
|
summary: Get a repo
|
|
description: Retrieves the details of a repository.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
schema:
|
|
$ref: "#/definitions/Repo"
|
|
404:
|
|
description: |
|
|
Unable to find the repository.
|
|
|
|
patch:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
- name: repo
|
|
in: body
|
|
description: The updated repository JSON
|
|
schema:
|
|
$ref: '#/definitions/Repo'
|
|
example: |
|
|
{
|
|
"timeout": 60,
|
|
"private": false,
|
|
"trusted": false,
|
|
"allow_pr": true,
|
|
"allow_push": true,
|
|
"allow_deploys": false,
|
|
"allow_tags": false
|
|
}
|
|
required: true
|
|
tags:
|
|
- Repos
|
|
summary: Updates a repo
|
|
description: Updates the specified repository.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
schema:
|
|
$ref: "#/definitions/Repo"
|
|
400:
|
|
description: |
|
|
Unable to update the repository in the database.
|
|
404:
|
|
description: |
|
|
Unable to find the repository.
|
|
|
|
post:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
tags:
|
|
- Repos
|
|
summary: Activates a repo
|
|
description: Activates a repository.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
schema:
|
|
$ref: "#/definitions/Repo"
|
|
400:
|
|
description: |
|
|
Unable to update the Repository record in the database
|
|
403:
|
|
description: |
|
|
Unable to activate the Repository due to insufficient privileges
|
|
404:
|
|
description: |
|
|
Unable to retrieve the Repository from the remote system (ie GitHub)
|
|
409:
|
|
description: |
|
|
Unable to activate the Repository because it is already activate
|
|
500:
|
|
description: |
|
|
Unable to activate the Repository due to an internal server error. This may indicate a problem adding hooks to the remote system (ie Github), generating SSH deployment keys, or persisting to the database.
|
|
|
|
delete:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
tags:
|
|
- Repos
|
|
summary: Delete a repo
|
|
description: Permanently deletes a repository. It cannot be undone.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: |
|
|
Successfully deleted the Repository
|
|
400:
|
|
description: |
|
|
Unable to remove post-commit hooks from the remote system (ie GitHub)
|
|
404:
|
|
description: |
|
|
Unable to find the Repository in the database
|
|
500:
|
|
description: |
|
|
Unable to update the Repository record in the database
|
|
|
|
|
|
#
|
|
# Repos Param Encryption Enpoint
|
|
# TODO: properly add the input output schema
|
|
|
|
/repos/{owner}/{name}/encrypt:
|
|
post:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
tags:
|
|
- Repos
|
|
summary: Encrypt repo secrets
|
|
description: Encryptes a Yaml file with secret environment variables for secure public storage.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The encrypted parameters.
|
|
400:
|
|
description: |
|
|
Unable to encrypt the parameters.
|
|
404:
|
|
description: |
|
|
Unable to find the repository.
|
|
|
|
|
|
#
|
|
# Builds Endpoint
|
|
#
|
|
|
|
/repos/{owner}/{name}/builds:
|
|
get:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
tags:
|
|
- Builds
|
|
summary: Get recent builds
|
|
description: Returns recent builds for the repository based on name.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The recent builds.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Build"
|
|
404:
|
|
description: |
|
|
Unable to find the Repository in the database
|
|
|
|
/repos/{owner}/{name}/builds/{number}:
|
|
get:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
- name: number
|
|
in: path
|
|
type: integer
|
|
description: sequential build number
|
|
tags:
|
|
- Builds
|
|
summary: Get a build
|
|
description: Returns the repository build by number.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The build.
|
|
schema:
|
|
$ref: "#/definitions/Build"
|
|
404:
|
|
description: |
|
|
Unable to find the Repository or Build
|
|
|
|
post:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
- name: number
|
|
in: path
|
|
type: integer
|
|
description: sequential build number
|
|
tags:
|
|
- Builds
|
|
summary: Restart a build
|
|
description: Restart the a build by number.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: Successfully restarted the Build.
|
|
schema:
|
|
$ref: "#/definitions/Build"
|
|
404:
|
|
description: |
|
|
Unable to find the Repository or Build.
|
|
409:
|
|
description: |
|
|
Cannot re-start a Build that is running.
|
|
|
|
|
|
#
|
|
# Jobs Endpoint
|
|
#
|
|
|
|
/repos/{owner}/{name}/logs/{number}/{job}:
|
|
get:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
- name: number
|
|
in: path
|
|
type: integer
|
|
description: sequential build number
|
|
- name: job
|
|
in: path
|
|
type: integer
|
|
description: sequential job number
|
|
tags:
|
|
- Builds
|
|
summary: Get build logs
|
|
description: Returns the build logs for a specific job (build step).
|
|
produces:
|
|
- text/plain
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The logs for the requested job.
|
|
404:
|
|
description: |
|
|
Unable to find the repository, build or job.
|
|
|
|
delete:
|
|
parameters:
|
|
- name: owner
|
|
in: path
|
|
type: string
|
|
description: owner of the repository
|
|
- name: name
|
|
in: path
|
|
type: string
|
|
description: name of the repository
|
|
- name: number
|
|
in: path
|
|
type: integer
|
|
description: sequential build number
|
|
- name: job
|
|
in: path
|
|
type: integer
|
|
description: sequential job number
|
|
tags:
|
|
- Builds
|
|
summary: Cancel a Job
|
|
description: Cancel the a build job by number.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: Successfully cancelled the Job
|
|
404:
|
|
description: |
|
|
Unable to find the Repository or Job
|
|
409:
|
|
description: |
|
|
Cannot cancel a Job that is already stopped
|
|
|
|
|
|
#
|
|
# User Endpoint
|
|
#
|
|
|
|
/user:
|
|
get:
|
|
summary: Gets a user
|
|
description: Returns the currently authenticated user.
|
|
security:
|
|
- accessToken: []
|
|
tags:
|
|
- User
|
|
responses:
|
|
200:
|
|
description: The currently authenticated user.
|
|
schema:
|
|
$ref: "#/definitions/User"
|
|
patch:
|
|
summary: Updates a user
|
|
description: Updates the currently authenticated user.
|
|
tags:
|
|
- User
|
|
parameters:
|
|
- name: user
|
|
in: body
|
|
description: Updates to the user.
|
|
required: true
|
|
schema:
|
|
$ref: "#/definitions/User"
|
|
responses:
|
|
200:
|
|
description: The updated user.
|
|
schema:
|
|
$ref: "#/definitions/User"
|
|
400:
|
|
description: |
|
|
Unable to update the user in the database
|
|
|
|
|
|
#
|
|
# User Repos
|
|
#
|
|
|
|
/user/repos:
|
|
get:
|
|
summary: Get user repos
|
|
description: |
|
|
Retrieve the currently authenticated User's Repository list
|
|
tags:
|
|
- User
|
|
responses:
|
|
200:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Repo"
|
|
400:
|
|
description: |
|
|
Unable to retrieve Repository list
|
|
|
|
|
|
#
|
|
# Users Endpoint
|
|
#
|
|
|
|
/users:
|
|
get:
|
|
tags:
|
|
- Users
|
|
summary: Get all users
|
|
description: Returns all registered, active users in the system.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: All registered users.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/User"
|
|
|
|
/users/{login}:
|
|
get:
|
|
parameters:
|
|
- name: login
|
|
in: path
|
|
type: string
|
|
description: user login
|
|
tags:
|
|
- Users
|
|
summary: Get a user
|
|
description: Returns a user with the specified login name.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: Returns the user.
|
|
schema:
|
|
$ref: "#/definitions/User"
|
|
404:
|
|
description: Cannot find user with matching login.
|
|
|
|
post:
|
|
parameters:
|
|
- name: login
|
|
in: path
|
|
type: string
|
|
description: user login to activate
|
|
tags:
|
|
- Users
|
|
summary: Create a user
|
|
description: Creates a new user account with the specified external login.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
201:
|
|
description: Returns the created user.
|
|
schema:
|
|
$ref: "#/definitions/User"
|
|
400:
|
|
description: |
|
|
Error inserting User into the database
|
|
|
|
patch:
|
|
parameters:
|
|
- name: login
|
|
in: path
|
|
type: string
|
|
description: user login
|
|
- name: user
|
|
in: body
|
|
description: changes to the user
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
example: |
|
|
{
|
|
"email": "octocat@github.com",
|
|
"admin": false,
|
|
"active": true
|
|
}
|
|
required: true
|
|
|
|
tags:
|
|
- Users
|
|
summary: Update a user
|
|
description: Updates an existing user account.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: Returns the updated user.
|
|
schema:
|
|
$ref: "#/definitions/User"
|
|
400:
|
|
description: |
|
|
Error updating the User in the database
|
|
|
|
delete:
|
|
parameters:
|
|
- name: login
|
|
in: path
|
|
type: string
|
|
description: user login
|
|
tags:
|
|
- Users
|
|
summary: Delete a user
|
|
description: Deletes the user with the specified login name.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
204:
|
|
description: |
|
|
Successfully deleted the User
|
|
400:
|
|
description: |
|
|
Error deleting the User from the database
|
|
403:
|
|
description: |
|
|
Cannot delete your own User account
|
|
404:
|
|
description: |
|
|
Cannot find the User
|
|
|
|
#
|
|
# Schema Definitions
|
|
#
|
|
|
|
definitions:
|
|
User:
|
|
example: |
|
|
{
|
|
"id": 1,
|
|
"login": "octocat",
|
|
"email": "octocat@github.com",
|
|
"avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
|
|
"admin": false,
|
|
"active": true
|
|
}
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
login:
|
|
type: string
|
|
email:
|
|
type: string
|
|
avatar_url:
|
|
type: string
|
|
admin:
|
|
type: boolean
|
|
active:
|
|
type: boolean
|
|
|
|
|
|
Repo:
|
|
example: |
|
|
{
|
|
"id": 1,
|
|
"owner": "octocat",
|
|
"name": "hello-world",
|
|
"full_name": "octocat/hello-world",
|
|
"avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
|
|
"link_url": "https://github.com/octocat/hello-world",
|
|
"clone_url": "https://github.com/octocat/hello-world.git",
|
|
"default_branch": "master",
|
|
"timeout": 60,
|
|
"private": false,
|
|
"trusted": false,
|
|
"allow_pr": true,
|
|
"allow_push": true,
|
|
"allow_deploys": false,
|
|
"allow_tags": false
|
|
}
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
owner:
|
|
type: string
|
|
name:
|
|
type: string
|
|
full_name:
|
|
type: string
|
|
avatar_url:
|
|
type: string
|
|
link_url:
|
|
type: string
|
|
clone_url:
|
|
type: string
|
|
default_branch:
|
|
type: string
|
|
private:
|
|
type: boolean
|
|
trusted:
|
|
type: boolean
|
|
timeout:
|
|
type: integer
|
|
allow_pr:
|
|
type: boolean
|
|
allow_push:
|
|
type: boolean
|
|
allow_deploys:
|
|
type: boolean
|
|
allow_tags:
|
|
type: boolean
|
|
|
|
|
|
Build:
|
|
example: |
|
|
{
|
|
"id": 1,
|
|
"number": 1,
|
|
"event": "push",
|
|
"status": "success",
|
|
"created_at": 1443677151,
|
|
"enqueued_at": 1443677151,
|
|
"started_at": 1443677151,
|
|
"finished_at": 1443677255,
|
|
"commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
|
|
"branch": "master",
|
|
"ref": "refs/heads/master",
|
|
"remote": "https://github.com/octocat/hello-world.git",
|
|
"message": "New line at end of file. --Signed off by Spaceghost",
|
|
"timestamp": 1443677255,
|
|
"author": "Spaceghost",
|
|
"author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
|
|
"author_email": "octocat@github.com",
|
|
"link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
|
|
"jobs": [
|
|
{
|
|
"id": 1,
|
|
"number": 1,
|
|
"status": "success",
|
|
"enqueued_at": 1443677151,
|
|
"started_at": 1443677151,
|
|
"finished_at": 1443677255,
|
|
"exit_code": 0,
|
|
"environment": { "GO_VERSION": "1.4" }
|
|
},
|
|
{
|
|
"id": 2,
|
|
"number": 2,
|
|
"status": "success",
|
|
"enqueued_at": 1443677151,
|
|
"started_at": 1443677151,
|
|
"finished_at": 1443677255,
|
|
"exit_code": 0,
|
|
"environment": { "GO_VERSION": "1.5" }
|
|
}
|
|
]
|
|
}
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
number:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
enum:
|
|
- success
|
|
- failure
|
|
- pending
|
|
- started
|
|
- error
|
|
- killed
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
enqueued_at:
|
|
type: integer
|
|
format: int64
|
|
started_at:
|
|
type: integer
|
|
format: int64
|
|
finished_at:
|
|
type: integer
|
|
format: int64
|
|
commit:
|
|
type: string
|
|
branch:
|
|
type: string
|
|
message:
|
|
type: string
|
|
timestamp:
|
|
type: integer
|
|
format: int64
|
|
ref:
|
|
type: string
|
|
refspec:
|
|
type: string
|
|
remote:
|
|
type: string
|
|
author:
|
|
type: string
|
|
author_avatar:
|
|
type: string
|
|
author_email:
|
|
type: string
|
|
link_url:
|
|
type: string
|
|
jobs:
|
|
type: array
|
|
items:
|
|
$ref: "#/definitions/Job"
|
|
|
|
Job:
|
|
example: |
|
|
{
|
|
"id": 1,
|
|
"number": 1,
|
|
"status": "success",
|
|
"enqueued_at": 1443677151,
|
|
"started_at": 1443677151,
|
|
"finished_at": 1443677255,
|
|
"exit_code": 0,
|
|
"environment": { "GO_VERSION": "1.4" }
|
|
}
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
number:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
enum:
|
|
- success
|
|
- failure
|
|
- pending
|
|
- started
|
|
- error
|
|
- killed
|
|
exit_code:
|
|
type: integer
|
|
enqueued_at:
|
|
type: integer
|
|
format: int64
|
|
started_at:
|
|
type: integer
|
|
format: int64
|
|
finished_at:
|
|
type: integer
|
|
format: int64
|
|
environment:
|
|
type: object
|
|
|
|
Feed:
|
|
example: |
|
|
{
|
|
"owner": "octocat",
|
|
"name": "hello-world",
|
|
"full_name": "octocat/hello-world",
|
|
"number": 1,
|
|
"event": "push",
|
|
"status": "success",
|
|
"created_at": 1443677151,
|
|
"enqueued_at": 1443677151,
|
|
"started_at": 1443677151,
|
|
"finished_at": 1443677255,
|
|
"commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
|
|
"branch": "master",
|
|
"ref": "refs/heads/master",
|
|
"remote": "https://github.com/octocat/hello-world.git",
|
|
"message": "New line at end of file. --Signed off by Spaceghost",
|
|
"timestamp": 1443677255,
|
|
"author": "Spaceghost",
|
|
"author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
|
|
"author_email": "octocat@github.com",
|
|
"link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
|
|
}
|
|
properties:
|
|
owner:
|
|
type: string
|
|
name:
|
|
type: string
|
|
full_name:
|
|
type: string
|
|
number:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
enum:
|
|
- success
|
|
- failure
|
|
- pending
|
|
- started
|
|
- error
|
|
- killed
|
|
created_at:
|
|
type: integer
|
|
format: int64
|
|
enqueued_at:
|
|
type: integer
|
|
format: int64
|
|
started_at:
|
|
type: integer
|
|
format: int64
|
|
finished_at:
|
|
type: integer
|
|
format: int64
|
|
commit:
|
|
type: string
|
|
branch:
|
|
type: string
|
|
message:
|
|
type: string
|
|
timestamp:
|
|
type: integer
|
|
format: int64
|
|
ref:
|
|
type: string
|
|
refspec:
|
|
type: string
|
|
remote:
|
|
type: string
|
|
author:
|
|
type: string
|
|
author_avatar:
|
|
type: string
|
|
author_email:
|
|
type: string
|
|
link_url:
|
|
type: string
|