2015-05-18 04:25:53 +02:00
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/"
2015-07-01 11:23:21 +02:00
2015-05-18 04:25:53 +02:00
host : "localhost:8080"
basePath : /api
schemes :
- http
2015-06-23 09:12:21 +02:00
- https
consumes :
- application/json
produces :
- application/json
2015-07-01 11:23:21 +02:00
#
# Operation tags
#
tags :
2015-07-02 08:22:05 +02:00
- name : Repos
- name : Builds
- name : Badges
- name : User
- name : Users
- name : Tokens
2015-07-01 11:23:21 +02:00
#
# Security Definitions
#
2015-06-23 09:12:21 +02:00
security :
- accessToken : [ ]
securityDefinitions :
accessToken :
type : apiKey
in : query
name : access_token
2015-07-01 11:23:21 +02:00
#
# Endpoint Definitions
#
2015-05-18 04:25:53 +02:00
paths :
2015-07-01 11:23:21 +02:00
#
# Repos Endpoint
#
2015-06-23 09:12:21 +02:00
/repos/{owner}/{name}:
get :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 09:12:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- Repos
2015-07-01 11:23:21 +02:00
summary : Get a repo
description : Retrieves the details of a repository.
2015-06-23 09:12:21 +02:00
security :
- accessToken : [ ]
responses :
2015-07-01 11:23:21 +02:00
200 :
2015-06-23 09:12:21 +02:00
schema :
$ref : "#/definitions/Repo"
2015-07-01 11:23:21 +02:00
404 :
description : |
Unable to find the repository.
2015-06-23 20:35:21 +02:00
patch :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 20:35:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-24 04:08:18 +02:00
- name : repo
in : body
description : The updated repository JSON
schema :
$ref : '#/definitions/Repo'
2015-07-01 11:23:21 +02:00
example : |
{
"trusted" : false ,
"timeout" : 60 ,
"hooks" : {
"pull_request" : true ,
"push" : true ,
"tags" : false
},
"keypair" : {
"public": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDwXK..." ,
"private": "-----BEGIN RSA PRIVATE KEY-----\nF7tLaAvx..."
},
"params": {
"HEROKU_KEY": "f0e4c2f76c58916ec258f24"
}
}
2015-06-24 04:08:18 +02:00
required : true
tags :
2015-07-02 08:22:05 +02:00
- Repos
2015-07-01 11:23:21 +02:00
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 :
2015-07-02 08:22:05 +02:00
- Repos
2015-07-01 11:23:21 +02:00
summary : Creates a repo
description : Creates a new repository.
2015-06-23 20:35:21 +02:00
security :
- accessToken : [ ]
responses :
2015-07-01 11:23:21 +02:00
200 :
2015-06-23 20:35:21 +02:00
schema :
$ref : "#/definitions/Repo"
2015-07-01 11:23:21 +02:00
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.
2015-06-23 20:35:21 +02:00
delete :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 20:35:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- Repos
2015-07-01 11:23:21 +02:00
summary : Delete a repo
description : Permanently deletes a repository. It cannot be undone.
2015-06-23 20:35:21 +02:00
security :
- accessToken : [ ]
2015-07-01 11:23:21 +02:00
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 Watch/Unwatch Enpoint
#
2015-06-23 20:35:21 +02:00
/repos/{owner}/{name}/watch:
post :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 20:35:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- Repos
2015-07-01 11:23:21 +02:00
summary : Watch
2015-06-23 20:35:21 +02:00
description : Watches the named repository.
security :
- accessToken : [ ]
2015-07-01 11:23:21 +02:00
responses :
200 :
description : |
Successfully watching this repository.
400 :
description : |
Unable to update the database.
404 :
description : |
Unable to find the repository.
2015-06-23 20:35:21 +02:00
/repos/{owner}/{name}/unwatch:
delete :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 20:35:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- Repos
2015-07-01 11:23:21 +02:00
summary : Unwatch
2015-06-23 20:35:21 +02:00
description : Unwatches the repository.
security :
- accessToken : [ ]
2015-07-01 11:23:21 +02:00
responses :
200 :
description : |
Successfully Unwatched this repository.
400 :
description : |
Unable to update the database.
404 :
description : |
Unable to find the repository.
#
# Builds Endpoint
#
2015-06-23 20:35:21 +02:00
/repos/{owner}/{name}/builds:
get :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 20:35:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- Builds
2015-07-01 11:23:21 +02:00
summary : Get recent builds
2015-06-23 20:35:21 +02:00
description : Returns recent builds for the repository based on name.
security :
- accessToken : [ ]
responses :
2015-07-01 11:23:21 +02:00
200 :
2015-06-23 20:35:21 +02:00
description : The recent builds.
schema :
type : array
items :
$ref : "#/definitions/Build"
2015-07-01 11:23:21 +02:00
404 :
description : |
Unable to find the Repository in the database
2015-06-23 20:35:21 +02:00
/repos/{owner}/{name}/builds/{number}:
get :
parameters :
- name : owner
in : path
type : string
2015-07-01 11:23:21 +02:00
description : owner of the repository
2015-06-23 20:35:21 +02:00
- name : name
in : path
type : string
2015-07-01 11:23:21 +02:00
description : name of the repository
2015-06-23 20:35:21 +02:00
- name : number
in : path
type : integer
2015-07-01 11:23:21 +02:00
description : sequential build number
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- Builds
2015-07-01 11:23:21 +02:00
summary : Get a build
2015-06-23 20:35:21 +02:00
description : Returns the repository build by number.
security :
- accessToken : [ ]
responses :
2015-07-01 11:23:21 +02:00
200 :
2015-06-23 20:35:21 +02:00
description : The build.
schema :
$ref : "#/definitions/Build"
2015-07-01 11:23:21 +02:00
404 :
description : |
2015-07-02 08:22:05 +02:00
Unable to find the Repository or Build
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
tags :
- Builds
summary : Cancel a build
description : Cancel the a build by number.
security :
- accessToken : [ ]
responses :
200 :
description : Successfully cancelled the Build
404 :
description : |
Unable to find the Repository or Build
409 :
description : |
Cannot cancel a Build that is already stopped
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.
2015-07-01 11:23:21 +02:00
2015-07-02 08:22:05 +02:00
/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.
2015-07-01 11:23:21 +02:00
#
# Badges
#
/badges/{owner}/{name}/status.svg:
get :
2015-07-02 08:22:05 +02:00
tags :
- Badges
produces :
- image/svg+xml
summary : Status Badge
2015-07-01 11:23:21 +02:00
description : Returns an SVG status badge for the latest Build
parameters :
- name : owner
in : path
type : string
description : owner of the repository
- name : name
in : path
type : string
description : name of the repository
- name : string
in : query
type : string
description : specify a branch. defaults to master
default : master
2015-07-02 08:22:05 +02:00
responses :
200 :
description : Status badge in SVG format
examples :
image/svg+xml : |
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" width="91" height="20">
<linearGradient id="a" x2="0" y2="100%">
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
<stop offset="1" stop-opacity=".1"/>
</linearGradient>
<rect rx="3" width="91" height="20" fill="#555"/>
<rect rx="3" x="37" width="54" height="20" fill="#4c1"/>
<path fill="#4c1" d="M37 0h4v20h-4z"/>
<rect rx="3" width="91" height="20" fill="url(#a)"/>
<g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
<text x="19.5" y="15" fill="#010101" fill-opacity=".3">build</text>
<text x="19.5" y="14">build</text>
<text x="63" y="15" fill="#010101" fill-opacity=".3">success</text>
<text x="63" y="14">success</text>
</g>
</svg>
2015-07-01 11:23:21 +02:00
/badges/{owner}/{name}/cc.xml:
get :
2015-07-02 08:22:05 +02:00
tags :
- Badges
summary : CCMenu
2015-07-01 11:23:21 +02:00
description : Returns a CCMenu feed for the Repository
parameters :
- name : owner
in : path
type : string
description : owner of the repository
- name : name
in : path
type : string
description : name of the repository
produces :
- application/xml
2015-07-02 08:22:05 +02:00
responses :
200 :
description : CCMenu XML feed object
examples :
application/xml : |
<Projects>
<Project name="octocat/octocat"
activity="Sleeping"
lastBuildStatus="Success"
lastBuildLabel="25"
lastBuildTime="2015-06-23T01:58:20-04:00" />
</Projects>
# application/xml: |
# <Projects>
# <Project name="octocat/octocat"
# activity="Sleeping"
# lastBuildStatus="Success"
# lastBuildLabel="25"
# lastBuildTime="2015-06-23T01:58:20-04:00" />
# </Projects>
2015-07-01 11:23:21 +02:00
#
# User Endpoint
#
2015-05-18 04:25:53 +02:00
/user :
get :
2015-07-01 11:23:21 +02:00
summary : Gets a user
2015-05-18 04:25:53 +02:00
description : Returns the currently authenticated user.
2015-06-23 09:12:21 +02:00
security :
- accessToken : [ ]
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- User
2015-05-18 04:25:53 +02:00
responses :
2015-07-01 11:23:21 +02:00
200 :
2015-05-18 04:25:53 +02:00
description : The currently authenticated user.
schema :
$ref : "#/definitions/User"
patch :
2015-07-01 11:23:21 +02:00
summary : Updates a user
2015-05-18 04:25:53 +02:00
description : Updates the currently authenticated user.
2015-06-24 04:08:18 +02:00
tags :
2015-07-02 08:22:05 +02:00
- User
2015-05-18 04:25:53 +02:00
parameters :
- name : user
in : body
description : Updates to the user.
required : true
schema :
$ref : "#/definitions/User"
responses :
2015-07-01 11:23:21 +02:00
200 :
2015-05-18 04:25:53 +02:00
description : The updated user.
schema :
$ref : "#/definitions/User"
2015-07-01 11:23:21 +02:00
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 :
2015-07-02 08:22:05 +02:00
- User
2015-07-01 11:23:21 +02:00
responses :
200 :
schema :
type : array
items :
$ref : "#/definitions/Repo"
400 :
description : |
Unable to retrieve Repository list
#
# User Tokens
#
/user/tokens :
get :
2015-07-02 08:22:05 +02:00
tags :
- Tokens
summary : Get all tokens
description : Returns all tokens for currently authenticated user.
security :
- accessToken : [ ]
responses :
200 :
description : All user tokens.
schema :
type : array
items :
$ref : "#/definitions/Token"
2015-07-01 11:23:21 +02:00
post :
2015-07-02 08:22:05 +02:00
parameters :
- name : token
description : Token input paraeters.
in : body
schema :
example : |
{
"label": "my_token"
}
tags :
- Tokens
summary : Create a token
description : Generates a new user access token.
security :
- accessToken : [ ]
responses :
200 :
description : The generated user token.
schema :
$ref : "#/definitions/Token"
400 :
description : |
Error when attempting to generate the JWT token
500 :
description : |
Error when attempting to save the Token
2015-07-01 11:23:21 +02:00
/user/tokens/{label}:
delete :
2015-07-02 08:22:05 +02:00
parameters :
- name : label
in : path
type : string
description : token label
tags :
- Tokens
summary : Delete a token
description : Revokes a token with the matching label.
security :
- accessToken : [ ]
responses :
200 :
description : |
Successfully deleted the Token
400 :
description : |
Error attempting to delete Token from database
404 :
description : |
Unable to find Token in database
2015-07-01 11:23:21 +02:00
#
# Users Endpoint
#
/users :
get :
tags :
2015-07-02 08:22:05 +02:00
- Users
2015-07-01 11:23:21 +02:00
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 :
2015-07-02 08:22:05 +02:00
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.
2015-07-01 11:23:21 +02:00
post :
2015-07-02 08:22:05 +02:00
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
2015-07-01 11:23:21 +02:00
patch :
2015-07-02 08:22:05 +02:00
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
2015-07-01 11:23:21 +02:00
delete :
2015-07-02 08:22:05 +02:00
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
2015-07-01 11:23:21 +02:00
#
# Schema Definitions
#
2015-05-18 04:25:53 +02:00
definitions :
User :
2015-07-01 11:23:21 +02:00
example : |
{
2015-07-02 08:22:05 +02:00
"login": "Octocat" ,
2015-07-01 11:23:21 +02:00
"email": "octocat@github.com" ,
2015-07-02 08:22:05 +02:00
"avatar": "7194e8d48fa1d2b689f99443b767316c" ,
2015-07-01 11:23:21 +02:00
"admin": false ,
"active": true
}
2015-05-18 04:25:53 +02:00
properties :
login :
type : string
email :
type : string
2015-08-03 08:50:08 +02:00
avatar :
2015-05-18 04:25:53 +02:00
type : string
admin :
type : boolean
active :
type : boolean
2015-07-01 11:23:21 +02:00
Token :
2015-07-02 08:22:05 +02:00
example : |
{
"label" : "my_token" ,
"issued_at" : 1435289846 ,
"hash" : "yUQJHM4YfNZcCLlikAshgjM6hCMlFXmHuABAECGsMQ"
}
2015-07-01 11:23:21 +02:00
properties :
issued_at :
type : integer
format : int64
label :
type : string
hash :
type : string
2015-05-18 04:25:53 +02:00
Repo :
2015-07-01 11:23:21 +02:00
example : |
{
"owner" : "drone" ,
"name" : "drone-test-go" ,
"full_name" : "drone/drone-test-go" ,
"self_url" : "http://localhost:8080/drone/drone-test-go" ,
"link_url" : "https://github.com/drone/drone-test-go" ,
"clone_url" : "https://github.com/drone/drone-test-go.git" ,
"default_branch" : "master" ,
"private" : true ,
"trusted" : false ,
"timeout" : 60 ,
"hooks" : {
"pull_request" : true ,
"push" : true ,
"tags" : false
},
"keypair" : {
"public": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDwXK..."
},
"permissions" : {
"pull" : true ,
"push" : true ,
"admin" : true
},
"params": {
"HEROKU_KEY": "f0e4c2f76c58916ec258f24"
}
}
2015-05-18 04:25:53 +02:00
properties :
owner :
type : string
name :
type : string
2015-06-23 09:12:21 +02:00
full_name :
type : string
link_url :
type : string
clone_url :
type : string
default_branch :
type : string
private :
type : boolean
trusted :
type : boolean
timeout :
type : integer
keypair :
type : object
properties :
public :
type : string
private :
type : string
hooks :
type : object
properties :
pull_request :
type : boolean
push :
type : boolean
tags :
type : boolean
permissions :
type : object
properties :
pull :
type : boolean
push :
type : boolean
admin :
type : boolean
params :
type : object
Build :
2015-07-01 11:23:21 +02:00
example : |
{
"number": 1 ,
"status": "success" ,
"started_at": 5788800 ,
"finished_at": 5789500 ,
"head_commit": {
"sha": "d101ef3ed6e973b039c3fd5ccdec378b0fa8684c" ,
"ref": "refs\/heads\/master" ,
"branch": "master" ,
"message": "updated the README.md file" ,
"timestamp": "" ,
"remote": "https:\/\/github.com\/drone\/drone.git" ,
"author": {
"login": "bradrydzewski" ,
"email": "brad.rydzewski@gmail.com"
}
},
"jobs": [
{
"number": 1 ,
"status": "success" ,
"started_at": 5788800 ,
"finished_at": 5789500 ,
"exit_code": 0 ,
"environment": { "GO_VERSION": "1.4" }
},
{
"number": 2 ,
"status": "success" ,
"started_at": 5788800 ,
"finished_at": 5789500 ,
"exit_code": 0 ,
"environment": { "GO_VERSION": "1.5" }
}
]
}
2015-05-18 04:25:53 +02:00
properties :
2015-06-23 09:12:21 +02:00
number :
2015-05-18 04:25:53 +02:00
type : integer
2015-06-23 09:12:21 +02:00
status :
2015-05-18 04:25:53 +02:00
type : string
2015-06-23 09:12:21 +02:00
enum :
- success
- failure
- pending
- started
- error
- killed
head_commit :
$ref : "#/definitions/Commit"
pull_request :
$ref : "#/definitions/PullRequest"
Commit :
properties :
2015-05-18 04:25:53 +02:00
sha :
type : string
ref :
type : string
branch :
type : string
2015-06-23 09:12:21 +02:00
message :
type : string
2015-05-18 04:25:53 +02:00
author :
2015-06-23 09:12:21 +02:00
$ref : "#/definitions/Author"
PullRequest :
properties :
number :
type : integer
title :
2015-05-18 04:25:53 +02:00
type : string
2015-06-23 09:12:21 +02:00
base_commit :
$ref : "#/definitions/Commit"
Author :
properties :
login :
2015-05-18 04:25:53 +02:00
type : string
2015-06-23 09:12:21 +02:00
email :
2015-05-18 04:25:53 +02:00
type : string
2015-06-23 09:12:21 +02:00
Job :
2015-05-18 04:25:53 +02:00
properties :
2015-06-23 09:12:21 +02:00
number :
2015-05-18 04:25:53 +02:00
type : integer
2015-06-23 09:12:21 +02:00
status :
2015-05-18 04:25:53 +02:00
type : string
2015-06-23 09:12:21 +02:00
enum :
- success
- failure
- pending
- started
- error
- killed
2015-05-18 04:25:53 +02:00
exit_code :
type : integer
started_at :
type : integer
format : int64
finished_at :
type : integer
format : int64
2015-06-23 09:12:21 +02:00
environment :
2015-06-23 20:35:21 +02:00
type : object