deciding if I like RAML or not

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

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" }
+    }
+  ]
+}

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"
+      }
+    },
+  }
+]

doc/samples/ccmenu.xml

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

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" }
+}

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"
+  }
+}

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
+    }
+  }
+]

doc/samples/token.json

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

doc/samples/tokens.json

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

doc/samples/user.json

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

doc/samples/users.json

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

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)