GitHub PullRequestReviewCommentEvent at 2014-01-24 14:45:11
Repository: badgekit-issue
Actor: andrewhayward
Payload: {"comment":{"url":"https://api.github.com/repos/mozilla/badgekit-issue/pulls/comments/9149769","id":9149769,"diff_hunk":"@@ -0,0 +1,367 @@\n+# Badges\n+\n+## `GET /badges`\n+\n+Retrieves all available badges\n+\n+### Expected request\n+\n+```\n+GET /badges HTTP/1.1\n+```\n+\n+#### Available request parameters\n+\n+* **`archived`:** `[true|false|any]`  \n+  Whether to include archived badges.\n+  * `true` will return only archived badges\n+  * `false` (default) will return only unarchived badges\n+  * `any` will return badges regardless of archived status\n+\n+### Expected response\n+\n+```\n+HTTP/1.1 200 OK\n+Content-Type: application/json\n+\n+{\n+  \"badges\": [\n+    {\n+      \"name\": \"Badge Name\",\n+      \"slug\": \"badge-slug\",\n+      \"strapline\": \"Badge Strapline\",\n+      \"description\": \"Badge Description\",\n+      \"imageURL\": \"http://example.org/badge.png\",\n+      \"archived\": false\n+    },\n+    ...\n+  ]\n+}\n+```\n+\n+### Potential errors\n+\n+*None*\n+\n+## `GET /badges/<slug>`\n+\n+Retrieves a specific badge.\n+\n+### Expected request\n+\n+```\n+GET /badges/<slug> HTTP/1.1\n+```\n+\n+### Expected response\n+\n+```\n+HTTP/1.1 200 OK\n+Content-Type: application/json\n+\n+{\n+  \"badge\": {\n+    \"name\": \"Badge Name\",\n+    \"slug\": \"badge-slug\",\n+    \"strapline\": \"Badge Strapline\",\n+    \"description\": \"Badge Description\",\n+    \"imageURL\": \"http://example.org/badge.png\",\n+    \"archived\": false\n+  }\n+}\n+```\n+\n+### Potential errors\n+\n+* **Badge not found**\n+\n+  ```\n+  HTTP/1.1 404 Not Found\n+  Content-Type: application/json\n+  \n+  {\n+    \"error\": \"not found\"\n+  }\n+  ```\n+\n+## `POST /badges`\n+\n+Creates a new badge.\n+\n+### Expected request\n+\n+Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`.\n+\n+```\n+POST /badges HTTP/1.1\n+Content-Type: application/json\n+\n+{\n+  \"name\": \"Badge Name\",\n+  \"slug\": \"badge-slug\",\n+  \"strapline\": \"Badge Strapline\",\n+  \"description\": \"Badge Description\",\n+  \"image\": \"http://example.org/image.png\"\n+}\n+```\n+\n+```\n+POST /badges HTTP/1.1\n+Content-Type: application/x-www-form-urlencoded\n+\n+name=Badge%20Name&slug=badge-slug&strapline=Badge%20Strapline&description=Badge%20Description&image=http%3A%2F%2Fexample.org%2Fimage.png\n+```\n+\n+```\n+POST /badges HTTP/1.1\n+Content-Type: multipart/form-data; boundary=…\n+\n+--…\n+content-disposition: form-data; name=\"name\"\n+\n+Badge Name\n+--…\n+content-disposition: form-data; name=\"slug\"\n+\n+badge-slug\n+--…\n+content-disposition: form-data; name=\"strapline\"\n+\n+Badge Strapline\n+--…\n+content-disposition: form-data; name=\"description\"\n+\n+Badge Description\n+--…\n+content-disposition: form-data; name=\"image\"\n+\n+http://example.org/image.png\n+--…--\n+```\n+\n+#### Alternatively…\n+\n+Images can be uploaded and hosted by the issuer API.\n+\n+```\n+POST /badges HTTP/1.1\n+Content-Type: application/json\n+\n+{\n+  …,\n+  \"image\": \"data:image/png;base64,…\"\n+}\n+```\n+\n+```\n+POST /badges HTTP/1.1\n+Content-Type: application/x-www-form-urlencoded\n+\n+…&image=data%3Aimage%2Fpng%3Bbase64%2C…\n+```\n+\n+```\n+POST /badges HTTP/1.1\n+Content-Type: multipart/form-data; boundary=…\n+\n+--…\n+…\n+--…\n+content-disposition: form-data; name=\"image\"; filename=\"…\"\n+Content-Type: image/png\n+Content-Transfer-Encoding: binary\n+\n+…\n+--…--\n+```\n+\n+### Expected response\n+\n+```\n+HTTP/1.1 201 Created\n+Content-Type: application/json\n+\n+{\n+  \"status\": \"created\"\n+}\n+```\n+\n+### Potential errors\n+\n+* **Invalid data**\n+  \n+  ```\n+  HTTP/1.1 400 Bad Request\n+  Content-Type: application/json\n+  \n+  {\n+    \"errors\": [\n+      {\n+        \"name\": \"ValidatorError\",\n+        \"message\": \"String is not in range\",\n+        \"field\": \"name\"\n+      },\n+      ...\n+    ]\n+  }\n+  ```\n+\n+* **Duplicate entry**\n+  \n+  ```\n+  HTTP/1.1 409 Conflict\n+  Content-Type: application/json\n+  \n+  {\n+    \"error\": \"A badge with that `slug` already exists\",\n+    \"received\": {\n+      \"name\": \"Badge Name\",\n+      \"slug\": \"badge-slug\",\n+      \"strapline\": \"Badge Strapline\",\n+      \"description\": \"Badge Description\",\n+      \"image\": \"http://example.org/image.png\"\n+    }\n+  }\n+  ```\n+\n+## `PUT /badges/<slug>`\n+\n+Updates an existing badge.\n+\n+### Expected request\n+\n+Requests can be sent as `application/json`, `application/x-www-form-urlencoded` or `multipart/form-data`.\n+\n+```\n+PUT /badges/<slug> HTTP/1.1\n+Content-Type: application/json\n+\n+{\n+  \"name\": \"New Badge Name\",\n+  \"slug\": \"new-badge-slug\",\n+  \"strapline\": \"New Badge Strapline\",\n+  \"description\": \"New Badge Description\",\n+  \"image\": \"http://example.org/new-image.png\"\n+}\n+```\n+\n+```\n+PUT /badges HTTP/1.1\n+Content-Type: application/x-www-form-urlencoded\n+\n+name=New%20Badge%20Name&new-slug=badge-slug&strapline=New%20Badge%20Strapline&description=New%20Badge%20Description&image=http%3A%2F%2Fexample.org%2Fnew-image.png\n+```\n+\n+```\n+PUT /badges HTTP/1.1\n+Content-Type: multipart/form-data; boundary=…\n+\n+--…\n+content-disposition: form-data; name=\"name\"\n+\n+New Badge Name\n+--…\n+content-disposition: form-data; name=\"slug\"\n+\n+new-badge-slug\n+--…\n+content-disposition: form-data; name=\"strapline\"\n+\n+New Badge Strapline\n+--…\n+content-disposition: form-data; name=\"description\"\n+\n+New Badge Description\n+--…\n+content-disposition: form-data; name=\"image\"\n+\n+http://example.org/new-image.png\n+--…--\n+```\n+\n+#### Alternatively…\n+\n+Images may be uploaded in the same manner as creating a new badge.\n+\n+### Expected response\n+\n+```\n+HTTP/1.1 200 OK\n+Content-Type: application/json\n+\n+{\n+  \"status\": \"updated\"","path":"docs/badges.md","position":293,"original_position":293,"commit_id":"c72d9e725c19badbe0667d64ae8f9d5ebb6dccd5","original_commit_id":"c72d9e725c19badbe0667d64ae8f9d5ebb6dccd5","user":{"login":"andrewhayward","id":159848,"avatar_url":"https://gravatar.com/avatar/8c9517be4c7cbb31f94d1a6a5e0dc09e?d=https%3A%2F%2Fidenticons.github.com%2F6ed977ec1a28f6703b401ed4db8305a6.png&r=x","gravatar_id":"8c9517be4c7cbb31f94d1a6a5e0dc09e","url":"https://api.github.com/users/andrewhayward","html_url":"https://github.com/andrewhayward","followers_url":"https://api.github.com/users/andrewhayward/followers","following_url":"https://api.github.com/users/andrewhayward/following{/other_user}","gists_url":"https://api.github.com/users/andrewhayward/gists{/gist_id}","starred_url":"https://api.github.com/users/andrewhayward/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/andrewhayward/subscriptions","organizations_url":"https://api.github.com/users/andrewhayward/orgs","repos_url":"https://api.github.com/users/andrewhayward/repos","events_url":"https://api.github.com/users/andrewhayward/events{/privacy}","received_events_url":"https://api.github.com/users/andrewhayward/received_events","type":"User","site_admin":false},"body":"Yeah, I think the updated badge is probably more important than a simple 'updated' message. We can worry about overhead later, if it becomes an issue.","created_at":"2014-01-24T14:45:11Z","updated_at":"2014-01-24T14:45:11Z","html_url":"https://github.com/mozilla/badgekit-issue/pull/16#discussion_r9149769","pull_request_url":"https://api.github.com/repos/mozilla/badgekit-issue/pulls/16","_links":{"self":{"href":"https://api.github.com/repos/mozilla/badgekit-issue/pulls/comments/9149769"},"html":{"href":"https://github.com/mozilla/badgekit-issue/pull/16#discussion_r9149769"},"pull_request":{"href":"https://api.github.com/repos/mozilla/badgekit-issue/pulls/16"}}}}