deciding if I like RAML or not

This commit is contained in:
Brad Rydzewski 2015-06-25 22:37:59 -07:00
parent 796ec75b38
commit bcb7e05cdc
12 changed files with 652 additions and 4 deletions

499
doc/api.raml Normal file
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View file

@ -0,0 +1,5 @@
{
"label":"brads_token",
"issued_at":1435289846,
"hash":"yUQJHM4YfNZcCLlikAshgjM6hCMlFXmHuABAECGsMQ"
}

6
doc/samples/tokens.json Normal file
View file

@ -0,0 +1,6 @@
[
{
"label":"brads_token",
"issued_at":1435289846
}
]

7
doc/samples/user.json Normal file
View 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
View file

@ -0,0 +1,9 @@
[
{
"name": "Octocat",
"email": "octocat@github.com",
"gravatar_id": "7194e8d48fa1d2b689f99443b767316c",
"admin": false,
"active": true
}
]

View file

@ -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)