woodpecker/doc/api.raml
2015-06-25 22:37:59 -07:00

499 lines
11 KiB
Text

#%RAML 0.8
title: Drone API
baseUri: http://localhost:8080/api
traits:
- authenticate:
description: Some requests require authentication.
queryParameters:
access_token:
description: Access Token
type: string
example: ACCESS_TOKEN
- authorize:
responses:
401:
description: |
Access Denied. User must be authenticated.
403:
description: |
Access Forbidden. User must be a system administrator.
/repos/{owner}/{name}:
is: [ authorize, authenticate ]
uriParameters:
owner:
displayName: Owner
description: Owner of the repository
type: string
required: true
name:
displayName: Name
description: Name of the repository
type: string
required: true
get:
displayName: Find Repository
description: |
Retrieve a Repository by Name
responses:
200:
body:
application/json:
example: !include samples/repo.json
404:
description: |
Unable to find the Repository in the database
patch:
displayName: Update Repository
description: |
Update a Repository
responses:
200:
body:
application/json:
example: !include samples/repo.json
400:
description: |
Unable to update the Repository record in the database
404:
description: |
Unable to find the Repository in the database
post:
displayName: Activate Repository
description: |
Activate a Repository
responses:
200:
body:
application/json:
example: !include samples/repo.json
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:
displayName: Delete Repository
description: |
Deletes a Repository
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
/watch:
is: [ authorize, authenticate ]
description: |
Watch the Repository
post:
responses:
200:
description: |
Successfully Watching this Repository
400:
description: |
Unable to insert the Starred record in the database
404:
description: |
Unable to find the Repository in the database
/unwatch:
is: [ authorize, authenticate ]
description: |
Unwatch the Repository
delete:
responses:
200:
description: |
Successfully Unwatched this Repository
400:
description: |
Unable to delete the Starred record in the database
404:
description: |
Unable to find the Repository in the database
#
# Builds
#
/repos/{owner}/{name}/builds:
displayName: Builds
is: [ authorize, authenticate ]
uriParameters:
owner:
displayName: Owner
description: Owner of the repository
type: string
required: true
name:
displayName: Name
description: Name of the repository
type: string
required: true
get:
displayName: List Builds
description: |
Retrieve the list of recent Builds for the Repository
responses:
200:
body:
application/json:
example: !include samples/builds.json
404:
description: |
Unable to find the Repository in the database
/{number}:
is: [ authorize, authenticate ]
uriParameters:
number:
displayName: Number
type: integer
get:
displayName: Find Build
description: |
Retrieve a specific Build by Number
responses:
200:
body:
application/json:
example: !include samples/build.json
404:
description: |
Unable to find the Build in the database
delete:
displayName: Cancel Build
description: |
Cancel an running Build by Number
responses:
200:
description: |
Successfully cancelled the Build
404:
description: |
Cannot find Build by Number
409:
description: |
Cannot cancel a Build that is already stopped
post:
displayName: Restart Build
description: |
Restart a completed Build
responses:
202:
description: |
Successfully cancelled the Build
404:
description: |
Cannot find Build by Number
409:
description: |
Cannot re-start a Build that is running
#
# Build Logs
#
/repos/{owner}/{name}/logs/{number}/{job}:
displayName: Builds
is: [ authorize, authenticate ]
uriParameters:
owner:
displayName: Owner
description: Owner of the repository
type: string
required: true
name:
displayName: Name
description: Name of the repository
type: string
required: true
number:
displayName: Build Number
description: Incremental Build Number
type: integer
required: true
job:
displayName: Job Number
description: Sequential Job Number
type: integer
required: true
get:
displayName: Find Build Logs
description: |
Retrieve the Logs for a specific Build Job
responses:
200:
body:
text/plain:
404:
description: |
Cannot find Build Logs
#
# User Endpoint
#
/user:
is: [ authorize, authenticate ]
displayName: User
get:
description: |
Retrieve the currently authenticated User
responses:
200:
body:
application/json:
example: !include samples/user.json
patch:
description: |
Update the currently authenticated User
responses:
200:
description: |
Updated User
body:
application/json:
example: !include samples/user.json
400:
description: |
Bad Request. Error updating User
#
# User Repos
#
/user/repos:
is: [ authorize, authenticate ]
displayName: User Repos
get:
description: |
Retrieve the currently authenticated User's Repository list
responses:
200:
body:
application/json:
example: !include samples/repos.json
400:
description: |
Bad Request. Error retrieving Repository list
#
# User Tokens
#
/user/tokens:
is: [ authorize, authenticate ]
displayName: User Tokens
get:
description: |
Retrieve the currently authenticated User's active Token list
responses:
200:
body:
application/json:
example: !include samples/tokens.json
400:
description: |
Error retrieving the Token list
post:
description: |
Generate a new User Token
responses:
200:
body:
application/json:
example: !include samples/token.json
400:
description: |
Error when attempting to generate the JWT token
500:
description: |
Error when attempting to save the Token
/{label}:
is: [ authorize, authenticate ]
delete:
description: |
Delete a specific User Token by Label
responses:
200:
description: |
Successfully deleted the Token
400:
description: |
Error attempting to delete Token from database
404:
description: |
Unable to find Token in database
#
# Users Endpoint
#
/users:
is: [ authorize, authenticate ]
displayName: Users
get:
description: Retrieve a list of all registered Users.
displayName: List Users
responses:
200:
body:
application/json:
example: !include samples/users.json
/{login}:
is: [ authorize, authenticate ]
uriParameters:
login:
displayName: Login
description: Username in remote system
example: Octocat
type: string
required: true
get:
displayName: Find User
description: |
Retrieve a specific User by Login name
responses:
200:
body:
application/json:
schema: !include schemas/user.json
404:
description: |
Cannot find the User
post:
displayName: Enable User
description: |
Enable a new User by Login name
responses:
201:
body:
application/json:
schema: !include schemas/user.json
400:
description: |
Error inserting User into the database
patch:
displayName: Update User
description: |
Update a specific User
responses:
200:
body:
application/json:
schema: !include schemas/user.json
400:
description: |
Error updating User record in the database
delete:
displayName: Delete User
description: |
Delete a specific User
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
#
# Badge Endpoint
#
/badges/{owner}/{name}:
displayName: Badges
uriParameters:
owner:
displayName: Owner
description: Owner of the repository
type: string
required: true
name:
displayName: Name
description: Name of the repository
type: string
required: true
/status.svg:
description: Returns an SVG status badge for the latest Build
displayName: Status Badge
get:
queryParameters:
branch:
default: master
required: false
type: string
example: master
responses:
200:
body:
image/svg+xml:
/cc.xml:
description: Returns a CCMenu feed for the Repository
displayName: CCMenu
get:
responses:
200:
body:
application/xml:
example: !include samples/ccmenu.xml