deciding if I like RAML or not
This commit is contained in:
parent
796ec75b38
commit
bcb7e05cdc
12 changed files with 652 additions and 4 deletions
499
doc/api.raml
Normal file
499
doc/api.raml
Normal file
|
@ -0,0 +1,499 @@
|
|||
#%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
|
38
doc/samples/build.json
Normal file
38
doc/samples/build.json
Normal file
|
@ -0,0 +1,38 @@
|
|||
{
|
||||
"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" }
|
||||
}
|
||||
]
|
||||
}
|
20
doc/samples/builds.json
Normal file
20
doc/samples/builds.json
Normal file
|
@ -0,0 +1,20 @@
|
|||
[
|
||||
{
|
||||
"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"
|
||||
}
|
||||
},
|
||||
}
|
||||
]
|
9
doc/samples/ccmenu.xml
Normal file
9
doc/samples/ccmenu.xml
Normal file
|
@ -0,0 +1,9 @@
|
|||
<Projects>
|
||||
<Project
|
||||
name="foo/bar"
|
||||
activity="Sleeping"
|
||||
lastBuildStatus="Success"
|
||||
lastBuildLabel="8e88d525"
|
||||
lastBuildTime="2015-06-24T14:27:49-04:00"
|
||||
webUrl="http://localhost:8080/foo/bar" />
|
||||
</Projects>
|
8
doc/samples/job.json
Normal file
8
doc/samples/job.json
Normal file
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"number": 1,
|
||||
"status": "success",
|
||||
"started_at": 5788800,
|
||||
"finished_at": 5789500,
|
||||
"exit_code": 0,
|
||||
"environment": { "GO_VERSION": "1.4" }
|
||||
}
|
28
doc/samples/repo.json
Normal file
28
doc/samples/repo.json
Normal file
|
@ -0,0 +1,28 @@
|
|||
{
|
||||
"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"
|
||||
}
|
||||
}
|
19
doc/samples/repos.json
Normal file
19
doc/samples/repos.json
Normal file
|
@ -0,0 +1,19 @@
|
|||
[
|
||||
{
|
||||
"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
|
||||
}
|
||||
}
|
||||
]
|
5
doc/samples/token.json
Normal file
5
doc/samples/token.json
Normal file
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label":"brads_token",
|
||||
"issued_at":1435289846,
|
||||
"hash":"yUQJHM4YfNZcCLlikAshgjM6hCMlFXmHuABAECGsMQ"
|
||||
}
|
6
doc/samples/tokens.json
Normal file
6
doc/samples/tokens.json
Normal file
|
@ -0,0 +1,6 @@
|
|||
[
|
||||
{
|
||||
"label":"brads_token",
|
||||
"issued_at":1435289846
|
||||
}
|
||||
]
|
7
doc/samples/user.json
Normal file
7
doc/samples/user.json
Normal file
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"name": "Octocat",
|
||||
"email": "octocat@github.com",
|
||||
"gravatar_id": "7194e8d48fa1d2b689f99443b767316c",
|
||||
"admin": false,
|
||||
"active": true
|
||||
}
|
9
doc/samples/users.json
Normal file
9
doc/samples/users.json
Normal file
|
@ -0,0 +1,9 @@
|
|||
[
|
||||
{
|
||||
"name": "Octocat",
|
||||
"email": "octocat@github.com",
|
||||
"gravatar_id": "7194e8d48fa1d2b689f99443b767316c",
|
||||
"admin": false,
|
||||
"active": true
|
||||
}
|
||||
]
|
|
@ -148,7 +148,7 @@ func DeleteRepo(c *gin.Context) {
|
|||
|
||||
err = ds.DelRepo(r)
|
||||
if err != nil {
|
||||
c.Fail(400, err)
|
||||
c.Fail(500, err)
|
||||
}
|
||||
c.Writer.WriteHeader(200)
|
||||
}
|
||||
|
@ -170,11 +170,11 @@ func PostRepo(c *gin.Context) {
|
|||
remote := ToRemote(c)
|
||||
r, err := remote.Repo(user, owner, name)
|
||||
if err != nil {
|
||||
c.Fail(400, err)
|
||||
c.Fail(404, err)
|
||||
}
|
||||
m, err := remote.Perm(user, owner, name)
|
||||
if err != nil {
|
||||
c.Fail(400, err)
|
||||
c.Fail(404, err)
|
||||
return
|
||||
}
|
||||
if !m.Admin {
|
||||
|
@ -220,7 +220,7 @@ func PostRepo(c *gin.Context) {
|
|||
// generate an RSA key and add to the repo
|
||||
key, err := sshutil.GeneratePrivateKey()
|
||||
if err != nil {
|
||||
c.Fail(400, err)
|
||||
c.Fail(500, err)
|
||||
return
|
||||
}
|
||||
r.Keys = new(common.Keypair)
|
||||
|
|
Loading…
Reference in a new issue