GitHub PullRequestReviewCommentEvent at 2014-12-04 16:47:23
Repository: courts-api
Actor: jamiecobbett
Payload: {"action":"created","comment":{"url":"https://api.github.com/repos/alphagov/courts-api/pulls/comments/21317262","id":21317262,"diff_hunk":"@@ -0,0 +1,193 @@\n+API Specification\n+=================\n+\n+This document is a DRAFT\n+\n+This specification describes the API through which MOJ's [court and tribunal finder](https://courttribunalfinder.service.gov.uk) sends court data to GDS in order to produce individual court pages on www.gov.uk. The administration and search functionality of courts are out of the scope of this document, as well as operational aspects such as message queuing, retry-on-error, logging and monitoring.\n+\n+Throughout this document, the term sender is used to refer to the system pushing the court data through the API, while the term receiver denotes the system receiving the data and publishing a representation of it online. The terms 'must', 'may' and 'should' follow the definitions in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)\n+\n+Principles\n+----------\n+\n+### How a court is described\n+\n+A court is described by a collection of properties encoded as text. For instance, the court's name, or its address, as well as some binary data representing a court's picture.\n+\n+Those properties are organised in a hierarchy. For instance, a court can have multiple addresses, each of which having one town name. JSON is used to serialise the textual data passed through the API, while JPG is used for encoding a court's picture.\n+\n+### Court identifiers\n+\n+A court is identified by a UUID, which the sender generates for new courts and uses to modify or delete existing courts. The format of court UUIDs must match the following regexp (in [Ruby syntax](http://ruby-doc.org/core-2.1.1/Regexp.html):\n+\n+    UUID_PATTERN = %r{\n+      \\A\n+      [a-f\\d]{8}\n+      -\n+      [a-f\\d]{4}\n+      -\n+      [1-5]   # Version: http://tools.ietf.org/html/rfc4122#section-4.1.3\n+      [a-f\\d]{3}\n+      -\n+      [89ab]  # Variant: http://tools.ietf.org/html/rfc4122#section-4.1.1\n+      [a-f\\d]{3}\n+      -\n+      [a-f\\d]{12}\n+      \\z\n+    }x\n+\n+From the [content-store on 23-12-2014](https://github.com/alphagov/content-store/blob/aa640fa8e29338afce5c4448d4c8b7a23fa06cbe/app/validators/uuid_validator.rb)\n+\n+A court's UUID must never change in the lifetime of a court. A UUID must also never be reused after a court has been deleted.\n+\n+\n+API calls\n+---------\n+\n+### Court creation or change\n+\n+    PUT https://{base}/{uuid}\n+\n+change or create a court.\n+\n+`base` is predefined by the receiver. The body of the request contains the description of the court, which must conform to the court JSON schema described below. Upon receiving the data, the receiver generates or updates a court page.\n+\n+On success, the receiver responds with a `201 Created` status code if a new court is created (as a result of the sender passing a new UUID passed in the request URL), or a `200 OK` if the call updates an existing court.\n+\n+In both cases, the body of the response must be a JSON string containing the full URL of the court's public page:\n+\n+    {\"public_url\":\"https://www.gov.uk/{prefix}/{slug}\"}\n+\n+The `prefix` is generated by the receiver and the `slug` must be the same as that passed in the court JSON object.\n+\n+The URL returned is not necessarily the URL that is passed in the PUT call.\n+\n+If a court's slug changes, the receiver must create HTTP redirects of the public URLs to avoid broken links.\n+\n+Errors are returned through standard HTTP response codes: 4XX on sender errors (eg, 422 if the court data passed is invalid) and 5XX on server errors. Response bodies should return helpful information about the error.\n+\n+### Court deletion\n+\n+In rare circumstances, typically following the mistaken creation of a court, a court's page needs to be removed from public view. The sender sends:\n+\n+    DELETE https://{base}/{uuid}\n+\n+The receiver must return one of the standard HTTP response codes, as above, with optional informative response body. The receiver must alter the corresponding court page so that it is no longer visible to the public. The UUID of a deleted court must never be reused.\n+\n+The sender must not use this API call to indicate that a court or a tribunal has been closed. In that case, a court modification request is sent, with `\"closed\":true` in the court data passed.\n+\n+### Fetching court information\n+\n+    GET https://{base}/{uuid}\n+\n+retrieve court data. If an existing UUID is passed, the receiver must return `200 OK`, and the response body must be the corresponding court object, which must conform to the JSON format for courts. The receiver returns `404 Not Found` in case no court exists with the UUID passed, or other standard error codes are sent in case of other errors.","path":"doc/api-specification.md","position":83,"original_position":83,"commit_id":"77b8ad01e594e2a127815f8cbf4b14a0372d1d8d","original_commit_id":"77b8ad01e594e2a127815f8cbf4b14a0372d1d8d","user":{"login":"jamiecobbett","id":93739,"avatar_url":"https://avatars.githubusercontent.com/u/93739?v=3","gravatar_id":"","url":"https://api.github.com/users/jamiecobbett","html_url":"https://github.com/jamiecobbett","followers_url":"https://api.github.com/users/jamiecobbett/followers","following_url":"https://api.github.com/users/jamiecobbett/following{/other_user}","gists_url":"https://api.github.com/users/jamiecobbett/gists{/gist_id}","starred_url":"https://api.github.com/users/jamiecobbett/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamiecobbett/subscriptions","organizations_url":"https://api.github.com/users/jamiecobbett/orgs","repos_url":"https://api.github.com/users/jamiecobbett/repos","events_url":"https://api.github.com/users/jamiecobbett/events{/privacy}","received_events_url":"https://api.github.com/users/jamiecobbett/received_events","type":"User","site_admin":false},"body":"Agreed on all counts :+1: ","created_at":"2014-12-04T16:47:23Z","updated_at":"2014-12-04T16:47:23Z","html_url":"https://github.com/alphagov/courts-api/pull/1#discussion_r21317262","pull_request_url":"https://api.github.com/repos/alphagov/courts-api/pulls/1","_links":{"self":{"href":"https://api.github.com/repos/alphagov/courts-api/pulls/comments/21317262"},"html":{"href":"https://github.com/alphagov/courts-api/pull/1#discussion_r21317262"},"pull_request":{"href":"https://api.github.com/repos/alphagov/courts-api/pulls/1"}}},"pull_request":{"url":"https://api.github.com/repos/alphagov/courts-api/pulls/1","id":25439428,"html_url":"https://github.com/alphagov/courts-api/pull/1","diff_url":"https://github.com/alphagov/courts-api/pull/1.diff","patch_url":"https://github.com/alphagov/courts-api/pull/1.patch","issue_url":"https://api.github.com/repos/alphagov/courts-api/issues/1","number":1,"state":"open","locked":false,"title":"first commit of api spec","user":{"login":"maxf","id":69542,"avatar_url":"https://avatars.githubusercontent.com/u/69542?v=3","gravatar_id":"","url":"https://api.github.com/users/maxf","html_url":"https://github.com/maxf","followers_url":"https://api.github.com/users/maxf/followers","following_url":"https://api.github.com/users/maxf/following{/other_user}","gists_url":"https://api.github.com/users/maxf/gists{/gist_id}","starred_url":"https://api.github.com/users/maxf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/maxf/subscriptions","organizations_url":"https://api.github.com/users/maxf/orgs","repos_url":"https://api.github.com/users/maxf/repos","events_url":"https://api.github.com/users/maxf/events{/privacy}","received_events_url":"https://api.github.com/users/maxf/received_events","type":"User","site_admin":false},"body":"","created_at":"2014-12-03T18:14:03Z","updated_at":"2014-12-04T16:47:23Z","closed_at":null,"merged_at":null,"merge_commit_sha":"b04dc2170f971160c87d0ffc9f886a6195e0a02a","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/alphagov/courts-api/pulls/1/commits","review_comments_url":"https://api.github.com/repos/alphagov/courts-api/pulls/1/comments","review_comment_url":"https://api.github.com/repos/alphagov/courts-api/pulls/comments/{number}","comments_url":"https://api.github.com/repos/alphagov/courts-api/issues/1/comments","statuses_url":"https://api.github.com/repos/alphagov/courts-api/statuses/77b8ad01e594e2a127815f8cbf4b14a0372d1d8d","head":{"label":"maxf:master","ref":"master","sha":"77b8ad01e594e2a127815f8cbf4b14a0372d1d8d","user":{"login":"maxf","id":69542,"avatar_url":"https://avatars.githubusercontent.com/u/69542?v=3","gravatar_id":"","url":"https://api.github.com/users/maxf","html_url":"https://github.com/maxf","followers_url":"https://api.github.com/users/maxf/followers","following_url":"https://api.github.com/users/maxf/following{/other_user}","gists_url":"https://api.github.com/users/maxf/gists{/gist_id}","starred_url":"https://api.github.com/users/maxf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/maxf/subscriptions","organizations_url":"https://api.github.com/users/maxf/orgs","repos_url":"https://api.github.com/users/maxf/repos","events_url":"https://api.github.com/users/maxf/events{/privacy}","received_events_url":"https://api.github.com/users/maxf/received_events","type":"User","site_admin":false},"repo":{"id":27500569,"name":"courts-api","full_name":"maxf/courts-api","owner":{"login":"maxf","id":69542,"avatar_url":"https://avatars.githubusercontent.com/u/69542?v=3","gravatar_id":"","url":"https://api.github.com/users/maxf","html_url":"https://github.com/maxf","followers_url":"https://api.github.com/users/maxf/followers","following_url":"https://api.github.com/users/maxf/following{/other_user}","gists_url":"https://api.github.com/users/maxf/gists{/gist_id}","starred_url":"https://api.github.com/users/maxf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/maxf/subscriptions","organizations_url":"https://api.github.com/users/maxf/orgs","repos_url":"https://api.github.com/users/maxf/repos","events_url":"https://api.github.com/users/maxf/events{/privacy}","received_events_url":"https://api.github.com/users/maxf/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/maxf/courts-api","description":"Provides an API for MOJ to publish courts and tribunals information to GOV.UK","fork":true,"url":"https://api.github.com/repos/maxf/courts-api","forks_url":"https://api.github.com/repos/maxf/courts-api/forks","keys_url":"https://api.github.com/repos/maxf/courts-api/keys{/key_id}","collaborators_url":"https://api.github.com/repos/maxf/courts-api/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/maxf/courts-api/teams","hooks_url":"https://api.github.com/repos/maxf/courts-api/hooks","issue_events_url":"https://api.github.com/repos/maxf/courts-api/issues/events{/number}","events_url":"https://api.github.com/repos/maxf/courts-api/events","assignees_url":"https://api.github.com/repos/maxf/courts-api/assignees{/user}","branches_url":"https://api.github.com/repos/maxf/courts-api/branches{/branch}","tags_url":"https://api.github.com/repos/maxf/courts-api/tags","blobs_url":"https://api.github.com/repos/maxf/courts-api/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/maxf/courts-api/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/maxf/courts-api/git/refs{/sha}","trees_url":"https://api.github.com/repos/maxf/courts-api/git/trees{/sha}","statuses_url":"https://api.github.com/repos/maxf/courts-api/statuses/{sha}","languages_url":"https://api.github.com/repos/maxf/courts-api/languages","stargazers_url":"https://api.github.com/repos/maxf/courts-api/stargazers","contributors_url":"https://api.github.com/repos/maxf/courts-api/contributors","subscribers_url":"https://api.github.com/repos/maxf/courts-api/subscribers","subscription_url":"https://api.github.com/repos/maxf/courts-api/subscription","commits_url":"https://api.github.com/repos/maxf/courts-api/commits{/sha}","git_commits_url":"https://api.github.com/repos/maxf/courts-api/git/commits{/sha}","comments_url":"https://api.github.com/repos/maxf/courts-api/comments{/number}","issue_comment_url":"https://api.github.com/repos/maxf/courts-api/issues/comments/{number}","contents_url":"https://api.github.com/repos/maxf/courts-api/contents/{+path}","compare_url":"https://api.github.com/repos/maxf/courts-api/compare/{base}...{head}","merges_url":"https://api.github.com/repos/maxf/courts-api/merges","archive_url":"https://api.github.com/repos/maxf/courts-api/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/maxf/courts-api/downloads","issues_url":"https://api.github.com/repos/maxf/courts-api/issues{/number}","pulls_url":"https://api.github.com/repos/maxf/courts-api/pulls{/number}","milestones_url":"https://api.github.com/repos/maxf/courts-api/milestones{/number}","notifications_url":"https://api.github.com/repos/maxf/courts-api/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/maxf/courts-api/labels{/name}","releases_url":"https://api.github.com/repos/maxf/courts-api/releases{/id}","created_at":"2014-12-03T18:10:34Z","updated_at":"2014-11-28T12:19:08Z","pushed_at":"2014-12-04T16:19:05Z","git_url":"git://github.com/maxf/courts-api.git","ssh_url":"git@github.com:maxf/courts-api.git","clone_url":"https://github.com/maxf/courts-api.git","svn_url":"https://github.com/maxf/courts-api","homepage":null,"size":0,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"alphagov:master","ref":"master","sha":"dbdf8d7fe5596a7969a56305d25d221ac2ae0741","user":{"login":"alphagov","id":596977,"avatar_url":"https://avatars.githubusercontent.com/u/596977?v=3","gravatar_id":"","url":"https://api.github.com/users/alphagov","html_url":"https://github.com/alphagov","followers_url":"https://api.github.com/users/alphagov/followers","following_url":"https://api.github.com/users/alphagov/following{/other_user}","gists_url":"https://api.github.com/users/alphagov/gists{/gist_id}","starred_url":"https://api.github.com/users/alphagov/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alphagov/subscriptions","organizations_url":"https://api.github.com/users/alphagov/orgs","repos_url":"https://api.github.com/users/alphagov/repos","events_url":"https://api.github.com/users/alphagov/events{/privacy}","received_events_url":"https://api.github.com/users/alphagov/received_events","type":"Organization","site_admin":false},"repo":{"id":27265867,"name":"courts-api","full_name":"alphagov/courts-api","owner":{"login":"alphagov","id":596977,"avatar_url":"https://avatars.githubusercontent.com/u/596977?v=3","gravatar_id":"","url":"https://api.github.com/users/alphagov","html_url":"https://github.com/alphagov","followers_url":"https://api.github.com/users/alphagov/followers","following_url":"https://api.github.com/users/alphagov/following{/other_user}","gists_url":"https://api.github.com/users/alphagov/gists{/gist_id}","starred_url":"https://api.github.com/users/alphagov/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alphagov/subscriptions","organizations_url":"https://api.github.com/users/alphagov/orgs","repos_url":"https://api.github.com/users/alphagov/repos","events_url":"https://api.github.com/users/alphagov/events{/privacy}","received_events_url":"https://api.github.com/users/alphagov/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/alphagov/courts-api","description":"Provides an API for MOJ to publish courts and tribunals information to GOV.UK","fork":false,"url":"https://api.github.com/repos/alphagov/courts-api","forks_url":"https://api.github.com/repos/alphagov/courts-api/forks","keys_url":"https://api.github.com/repos/alphagov/courts-api/keys{/key_id}","collaborators_url":"https://api.github.com/repos/alphagov/courts-api/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/alphagov/courts-api/teams","hooks_url":"https://api.github.com/repos/alphagov/courts-api/hooks","issue_events_url":"https://api.github.com/repos/alphagov/courts-api/issues/events{/number}","events_url":"https://api.github.com/repos/alphagov/courts-api/events","assignees_url":"https://api.github.com/repos/alphagov/courts-api/assignees{/user}","branches_url":"https://api.github.com/repos/alphagov/courts-api/branches{/branch}","tags_url":"https://api.github.com/repos/alphagov/courts-api/tags","blobs_url":"https://api.github.com/repos/alphagov/courts-api/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/alphagov/courts-api/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/alphagov/courts-api/git/refs{/sha}","trees_url":"https://api.github.com/repos/alphagov/courts-api/git/trees{/sha}","statuses_url":"https://api.github.com/repos/alphagov/courts-api/statuses/{sha}","languages_url":"https://api.github.com/repos/alphagov/courts-api/languages","stargazers_url":"https://api.github.com/repos/alphagov/courts-api/stargazers","contributors_url":"https://api.github.com/repos/alphagov/courts-api/contributors","subscribers_url":"https://api.github.com/repos/alphagov/courts-api/subscribers","subscription_url":"https://api.github.com/repos/alphagov/courts-api/subscription","commits_url":"https://api.github.com/repos/alphagov/courts-api/commits{/sha}","git_commits_url":"https://api.github.com/repos/alphagov/courts-api/git/commits{/sha}","comments_url":"https://api.github.com/repos/alphagov/courts-api/comments{/number}","issue_comment_url":"https://api.github.com/repos/alphagov/courts-api/issues/comments/{number}","contents_url":"https://api.github.com/repos/alphagov/courts-api/contents/{+path}","compare_url":"https://api.github.com/repos/alphagov/courts-api/compare/{base}...{head}","merges_url":"https://api.github.com/repos/alphagov/courts-api/merges","archive_url":"https://api.github.com/repos/alphagov/courts-api/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/alphagov/courts-api/downloads","issues_url":"https://api.github.com/repos/alphagov/courts-api/issues{/number}","pulls_url":"https://api.github.com/repos/alphagov/courts-api/pulls{/number}","milestones_url":"https://api.github.com/repos/alphagov/courts-api/milestones{/number}","notifications_url":"https://api.github.com/repos/alphagov/courts-api/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/alphagov/courts-api/labels{/name}","releases_url":"https://api.github.com/repos/alphagov/courts-api/releases{/id}","created_at":"2014-11-28T12:19:08Z","updated_at":"2014-11-28T12:19:08Z","pushed_at":"2014-12-03T18:27:23Z","git_url":"git://github.com/alphagov/courts-api.git","ssh_url":"git@github.com:alphagov/courts-api.git","clone_url":"https://github.com/alphagov/courts-api.git","svn_url":"https://github.com/alphagov/courts-api","homepage":null,"size":0,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":1,"forks":1,"open_issues":1,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/alphagov/courts-api/pulls/1"},"html":{"href":"https://github.com/alphagov/courts-api/pull/1"},"issue":{"href":"https://api.github.com/repos/alphagov/courts-api/issues/1"},"comments":{"href":"https://api.github.com/repos/alphagov/courts-api/issues/1/comments"},"review_comments":{"href":"https://api.github.com/repos/alphagov/courts-api/pulls/1/comments"},"review_comment":{"href":"https://api.github.com/repos/alphagov/courts-api/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/alphagov/courts-api/pulls/1/commits"},"statuses":{"href":"https://api.github.com/repos/alphagov/courts-api/statuses/77b8ad01e594e2a127815f8cbf4b14a0372d1d8d"}}}}