499 lines
11 KiB
Text
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 restarted 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
|