From bcb7e05cdc6c7e0dbdfb2be74652146b22eb73d4 Mon Sep 17 00:00:00 2001 From: Brad Rydzewski Date: Thu, 25 Jun 2015 22:37:59 -0700 Subject: [PATCH] deciding if I like RAML or not --- doc/api.raml | 499 ++++++++++++++++++++++++++++++++++++++++ doc/samples/build.json | 38 +++ doc/samples/builds.json | 20 ++ doc/samples/ccmenu.xml | 9 + doc/samples/job.json | 8 + doc/samples/repo.json | 28 +++ doc/samples/repos.json | 19 ++ doc/samples/token.json | 5 + doc/samples/tokens.json | 6 + doc/samples/user.json | 7 + doc/samples/users.json | 9 + pkg/server/repos.go | 8 +- 12 files changed, 652 insertions(+), 4 deletions(-) create mode 100644 doc/api.raml create mode 100644 doc/samples/build.json create mode 100644 doc/samples/builds.json create mode 100644 doc/samples/ccmenu.xml create mode 100644 doc/samples/job.json create mode 100644 doc/samples/repo.json create mode 100644 doc/samples/repos.json create mode 100644 doc/samples/token.json create mode 100644 doc/samples/tokens.json create mode 100644 doc/samples/user.json create mode 100644 doc/samples/users.json diff --git a/doc/api.raml b/doc/api.raml new file mode 100644 index 000000000..b4cabeaf8 --- /dev/null +++ b/doc/api.raml @@ -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 diff --git a/doc/samples/build.json b/doc/samples/build.json new file mode 100644 index 000000000..c82440d2f --- /dev/null +++ b/doc/samples/build.json @@ -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" } + } + ] +} diff --git a/doc/samples/builds.json b/doc/samples/builds.json new file mode 100644 index 000000000..5fd051e67 --- /dev/null +++ b/doc/samples/builds.json @@ -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" + } + }, + } +] diff --git a/doc/samples/ccmenu.xml b/doc/samples/ccmenu.xml new file mode 100644 index 000000000..77f14833a --- /dev/null +++ b/doc/samples/ccmenu.xml @@ -0,0 +1,9 @@ + + + diff --git a/doc/samples/job.json b/doc/samples/job.json new file mode 100644 index 000000000..401df22fa --- /dev/null +++ b/doc/samples/job.json @@ -0,0 +1,8 @@ +{ + "number": 1, + "status": "success", + "started_at": 5788800, + "finished_at": 5789500, + "exit_code": 0, + "environment": { "GO_VERSION": "1.4" } +} diff --git a/doc/samples/repo.json b/doc/samples/repo.json new file mode 100644 index 000000000..a0dffe85b --- /dev/null +++ b/doc/samples/repo.json @@ -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" + } +} diff --git a/doc/samples/repos.json b/doc/samples/repos.json new file mode 100644 index 000000000..1f2871754 --- /dev/null +++ b/doc/samples/repos.json @@ -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 + } + } +] diff --git a/doc/samples/token.json b/doc/samples/token.json new file mode 100644 index 000000000..570ba7574 --- /dev/null +++ b/doc/samples/token.json @@ -0,0 +1,5 @@ +{ + "label":"brads_token", + "issued_at":1435289846, + "hash":"yUQJHM4YfNZcCLlikAshgjM6hCMlFXmHuABAECGsMQ" +} diff --git a/doc/samples/tokens.json b/doc/samples/tokens.json new file mode 100644 index 000000000..0bb1bf93d --- /dev/null +++ b/doc/samples/tokens.json @@ -0,0 +1,6 @@ +[ + { + "label":"brads_token", + "issued_at":1435289846 + } +] diff --git a/doc/samples/user.json b/doc/samples/user.json new file mode 100644 index 000000000..d9b33dd48 --- /dev/null +++ b/doc/samples/user.json @@ -0,0 +1,7 @@ +{ + "name": "Octocat", + "email": "octocat@github.com", + "gravatar_id": "7194e8d48fa1d2b689f99443b767316c", + "admin": false, + "active": true +} diff --git a/doc/samples/users.json b/doc/samples/users.json new file mode 100644 index 000000000..1725214df --- /dev/null +++ b/doc/samples/users.json @@ -0,0 +1,9 @@ +[ + { + "name": "Octocat", + "email": "octocat@github.com", + "gravatar_id": "7194e8d48fa1d2b689f99443b767316c", + "admin": false, + "active": true + } +] diff --git a/pkg/server/repos.go b/pkg/server/repos.go index 0b9aeb31d..9051a1dc8 100644 --- a/pkg/server/repos.go +++ b/pkg/server/repos.go @@ -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)