{"action":"created","comment":{"url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/comments/25521920","id":25521920,"diff_hunk":"@@ -11,477 +12,247 @@ Gist is a paste. A snippet of text. Not unrelated to [GitHub Gists][].  To set s\n > + [API Blueprint Map][map]\n > + [Tools for API Blueprint][Tooling Section]\n \n-## Gist Fox API\n-Without any further ado our *Gist Fox API* blueprint starts like this:\n-\n-    FORMAT: 1A\n-\n-    # Gist Fox API\n-    Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).\n-\n-What have we just done? Let's break it line by line:\n-\n-#### Metadata\n-\n-    FORMAT: 1A\n-\n-Depending on the tools you will be using with your blueprint you might want to start your blueprint file with a metadata explicitly stating the API Blueprint version you want to use like in this case the version 1A.\n-\n-> **Note:** Should you need a clarification of some terms as used through this document refer to [API Blueprint Glossary of Terms][].\n-\n-#### API Name\n-\n-    # Gist Fox API\n-\n-Every good API should have a name. So does ours – *\"Gist Fox API\"*. The first Markdown header in our document represents just that – the API name.\n-\n-#### API Description\n-\n-    Gist Fox API is a **pastes service** similar to [GitHub's Gist][http://gist.github.com].\n-\n-The API Name might be followed by any arbitrary Markdown-formatted discussion. Preferably about your API.\n-\n-> **Note:** We will add much richer and more helpful discussion in the final version of this blueprint. Adding details about authentication, used media types and error handling to API description is always a great idea!\n->\n-> **Note:** For the sake of simplicity we will now omit user management and authentication. These features will be discussed in a future instalment of the API Blueprint Tutorial.\n-\n-## Markdown\n-All you really need to write a blueprint is a text editor. A Markdown editor is even better. Anything you like. From Vi to Byword. Online editors are great too! You can even directly edit a blueprint on GitHub in the repository your service is living!\n-\n-If you are completely new to Markdown it is now the best time to learn about it. Just head over to [Markdown Tutorial][] and enjoy the ride. Just don't forget to come back we have some cool stuff too!\n-\n-Should you just need to refresh Markdown syntax you can always check the one and only [Gruber's Original][] documentation.\n-\n->  **Note:** It is not essentially required to know the Markdown syntax but it will help you a lot. The knowledge of Markdown will make some API Blueprint constructs more intuitive.\n-\n-## First Resource\n-The first resource in our API is its root. The entry point to our API is defined like so:\n+## API Blueprint\n \n-    # Gist Fox API Root [/]\n-    Gist Fox API entry point.\n+The start of the Blueprint is going to look as follows:\n \n-    This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and HAL links.\n+```markdown\n+FORMAT: 1A\n \n-    ## Retrieve Entry Point [GET]\n+# Polls\n \n-    + Response 200 (application/hal+json)\n-        + Headers\n+Polls is a simple web service that allows consumers to view polls and vote in them.\n+```\n \n-                Link: <http:/api.gistfox.com/>;rel=\"self\",<http:/api.gistfox.com/gists>;rel=\"gists\"\n+## Metadata\n \n-        + Body\n-\n-                {\n-                    \"_links\": {\n-                        \"self\": { \"href\": \"/\" },\n-                        \"gists\": { \"href\": \"/gists?{since}\", \"templated\": true }\n-                    }\n-                }\n+At the very top of this Blueprint, you will find a metadata section. In this case we have specified that `FORMAT` has the value of `1A`. The format keyword is used to specify the version of the API Blueprint. In this case 1A.","path":"Tutorial.md","position":89,"original_position":89,"commit_id":"3238b5d8d4f649a6605cbf4bce3e38fb77354395","original_commit_id":"3238b5d8d4f649a6605cbf4bce3e38fb77354395","user":{"login":"smizell","id":130959,"avatar_url":"https://avatars.githubusercontent.com/u/130959?v=3","gravatar_id":"","url":"https://api.github.com/users/smizell","html_url":"https://github.com/smizell","followers_url":"https://api.github.com/users/smizell/followers","following_url":"https://api.github.com/users/smizell/following{/other_user}","gists_url":"https://api.github.com/users/smizell/gists{/gist_id}","starred_url":"https://api.github.com/users/smizell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smizell/subscriptions","organizations_url":"https://api.github.com/users/smizell/orgs","repos_url":"https://api.github.com/users/smizell/repos","events_url":"https://api.github.com/users/smizell/events{/privacy}","received_events_url":"https://api.github.com/users/smizell/received_events","type":"User","site_admin":false},"body":"I would sync up your language with my [comment here](https://github.com/apiaryio/api-blueprint/pull/154/files#r25521731) about \"starting\" or \"beginning.\" It seems like the language should be beginning, middle, end rather than top, middle, bottom. You usually refer to writing as the former, maybe?","created_at":"2015-02-27T17:18:44Z","updated_at":"2015-02-27T17:18:44Z","html_url":"https://github.com/apiaryio/api-blueprint/pull/154#discussion_r25521920","pull_request_url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154","_links":{"self":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/comments/25521920"},"html":{"href":"https://github.com/apiaryio/api-blueprint/pull/154#discussion_r25521920"},"pull_request":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154"}}},"pull_request":{"url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154","id":29605334,"html_url":"https://github.com/apiaryio/api-blueprint/pull/154","diff_url":"https://github.com/apiaryio/api-blueprint/pull/154.diff","patch_url":"https://github.com/apiaryio/api-blueprint/pull/154.patch","issue_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/154","number":154,"state":"open","locked":false,"title":"Simpler API Blueprint Tutorial","user":{"login":"kylef","id":44164,"avatar_url":"https://avatars.githubusercontent.com/u/44164?v=3","gravatar_id":"","url":"https://api.github.com/users/kylef","html_url":"https://github.com/kylef","followers_url":"https://api.github.com/users/kylef/followers","following_url":"https://api.github.com/users/kylef/following{/other_user}","gists_url":"https://api.github.com/users/kylef/gists{/gist_id}","starred_url":"https://api.github.com/users/kylef/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kylef/subscriptions","organizations_url":"https://api.github.com/users/kylef/orgs","repos_url":"https://api.github.com/users/kylef/repos","events_url":"https://api.github.com/users/kylef/events{/privacy}","received_events_url":"https://api.github.com/users/kylef/received_events","type":"User","site_admin":false},"body":"These changes make the new tutorial shorter, and simpler while requiring less prerequisites. The tutorial has no expectations of the user knowing Markdown.\r\n\r\nWould appreciate any feedback on this one to ensure we get this right.","created_at":"2015-02-19T11:53:41Z","updated_at":"2015-02-27T17:18:44Z","closed_at":null,"merged_at":null,"merge_commit_sha":"1dc410f961ed6b08ec049566c5161e8c38b558b4","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154/commits","review_comments_url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154/comments","review_comment_url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/comments{/number}","comments_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/154/comments","statuses_url":"https://api.github.com/repos/apiaryio/api-blueprint/statuses/3238b5d8d4f649a6605cbf4bce3e38fb77354395","head":{"label":"apiaryio:kylef/polls-tutorial","ref":"kylef/polls-tutorial","sha":"3238b5d8d4f649a6605cbf4bce3e38fb77354395","user":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"repo":{"id":9711133,"name":"api-blueprint","full_name":"apiaryio/api-blueprint","owner":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apiaryio/api-blueprint","description":"API Blueprint","fork":false,"url":"https://api.github.com/repos/apiaryio/api-blueprint","forks_url":"https://api.github.com/repos/apiaryio/api-blueprint/forks","keys_url":"https://api.github.com/repos/apiaryio/api-blueprint/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apiaryio/api-blueprint/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apiaryio/api-blueprint/teams","hooks_url":"https://api.github.com/repos/apiaryio/api-blueprint/hooks","issue_events_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/events{/number}","events_url":"https://api.github.com/repos/apiaryio/api-blueprint/events","assignees_url":"https://api.github.com/repos/apiaryio/api-blueprint/assignees{/user}","branches_url":"https://api.github.com/repos/apiaryio/api-blueprint/branches{/branch}","tags_url":"https://api.github.com/repos/apiaryio/api-blueprint/tags","blobs_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/refs{/sha}","trees_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apiaryio/api-blueprint/statuses/{sha}","languages_url":"https://api.github.com/repos/apiaryio/api-blueprint/languages","stargazers_url":"https://api.github.com/repos/apiaryio/api-blueprint/stargazers","contributors_url":"https://api.github.com/repos/apiaryio/api-blueprint/contributors","subscribers_url":"https://api.github.com/repos/apiaryio/api-blueprint/subscribers","subscription_url":"https://api.github.com/repos/apiaryio/api-blueprint/subscription","commits_url":"https://api.github.com/repos/apiaryio/api-blueprint/commits{/sha}","git_commits_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/commits{/sha}","comments_url":"https://api.github.com/repos/apiaryio/api-blueprint/comments{/number}","issue_comment_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/comments{/number}","contents_url":"https://api.github.com/repos/apiaryio/api-blueprint/contents/{+path}","compare_url":"https://api.github.com/repos/apiaryio/api-blueprint/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apiaryio/api-blueprint/merges","archive_url":"https://api.github.com/repos/apiaryio/api-blueprint/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apiaryio/api-blueprint/downloads","issues_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues{/number}","pulls_url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls{/number}","milestones_url":"https://api.github.com/repos/apiaryio/api-blueprint/milestones{/number}","notifications_url":"https://api.github.com/repos/apiaryio/api-blueprint/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apiaryio/api-blueprint/labels{/name}","releases_url":"https://api.github.com/repos/apiaryio/api-blueprint/releases{/id}","created_at":"2013-04-27T07:34:33Z","updated_at":"2015-02-27T16:23:27Z","pushed_at":"2015-02-27T16:01:13Z","git_url":"git://github.com/apiaryio/api-blueprint.git","ssh_url":"git@github.com:apiaryio/api-blueprint.git","clone_url":"https://github.com/apiaryio/api-blueprint.git","svn_url":"https://github.com/apiaryio/api-blueprint","homepage":"http://apiblueprint.org","size":6205,"stargazers_count":1814,"watchers_count":1814,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":549,"mirror_url":null,"open_issues_count":38,"forks":549,"open_issues":38,"watchers":1814,"default_branch":"master"}},"base":{"label":"apiaryio:master","ref":"master","sha":"b8004901bf4e166b06a17eb91721ae0d9b92e8e7","user":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"repo":{"id":9711133,"name":"api-blueprint","full_name":"apiaryio/api-blueprint","owner":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apiaryio/api-blueprint","description":"API Blueprint","fork":false,"url":"https://api.github.com/repos/apiaryio/api-blueprint","forks_url":"https://api.github.com/repos/apiaryio/api-blueprint/forks","keys_url":"https://api.github.com/repos/apiaryio/api-blueprint/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apiaryio/api-blueprint/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apiaryio/api-blueprint/teams","hooks_url":"https://api.github.com/repos/apiaryio/api-blueprint/hooks","issue_events_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/events{/number}","events_url":"https://api.github.com/repos/apiaryio/api-blueprint/events","assignees_url":"https://api.github.com/repos/apiaryio/api-blueprint/assignees{/user}","branches_url":"https://api.github.com/repos/apiaryio/api-blueprint/branches{/branch}","tags_url":"https://api.github.com/repos/apiaryio/api-blueprint/tags","blobs_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/refs{/sha}","trees_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apiaryio/api-blueprint/statuses/{sha}","languages_url":"https://api.github.com/repos/apiaryio/api-blueprint/languages","stargazers_url":"https://api.github.com/repos/apiaryio/api-blueprint/stargazers","contributors_url":"https://api.github.com/repos/apiaryio/api-blueprint/contributors","subscribers_url":"https://api.github.com/repos/apiaryio/api-blueprint/subscribers","subscription_url":"https://api.github.com/repos/apiaryio/api-blueprint/subscription","commits_url":"https://api.github.com/repos/apiaryio/api-blueprint/commits{/sha}","git_commits_url":"https://api.github.com/repos/apiaryio/api-blueprint/git/commits{/sha}","comments_url":"https://api.github.com/repos/apiaryio/api-blueprint/comments{/number}","issue_comment_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/comments{/number}","contents_url":"https://api.github.com/repos/apiaryio/api-blueprint/contents/{+path}","compare_url":"https://api.github.com/repos/apiaryio/api-blueprint/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apiaryio/api-blueprint/merges","archive_url":"https://api.github.com/repos/apiaryio/api-blueprint/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apiaryio/api-blueprint/downloads","issues_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues{/number}","pulls_url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls{/number}","milestones_url":"https://api.github.com/repos/apiaryio/api-blueprint/milestones{/number}","notifications_url":"https://api.github.com/repos/apiaryio/api-blueprint/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apiaryio/api-blueprint/labels{/name}","releases_url":"https://api.github.com/repos/apiaryio/api-blueprint/releases{/id}","created_at":"2013-04-27T07:34:33Z","updated_at":"2015-02-27T16:23:27Z","pushed_at":"2015-02-27T16:01:13Z","git_url":"git://github.com/apiaryio/api-blueprint.git","ssh_url":"git@github.com:apiaryio/api-blueprint.git","clone_url":"https://github.com/apiaryio/api-blueprint.git","svn_url":"https://github.com/apiaryio/api-blueprint","homepage":"http://apiblueprint.org","size":6205,"stargazers_count":1814,"watchers_count":1814,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":549,"mirror_url":null,"open_issues_count":38,"forks":549,"open_issues":38,"watchers":1814,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154"},"html":{"href":"https://github.com/apiaryio/api-blueprint/pull/154"},"issue":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/issues/154"},"comments":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/issues/154/comments"},"review_comments":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154/comments"},"review_comment":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/154/commits"},"statuses":{"href":"https://api.github.com/repos/apiaryio/api-blueprint/statuses/3238b5d8d4f649a6605cbf4bce3e38fb77354395"}}}}