{"action":"created","comment":{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments/82833703","pull_request_review_id":3712978,"id":82833703,"diff_hunk":"@@ -2,15 +2,60 @@\n \n The titles are marked with the corresponding labels: {{ book.must }}, {{ book.should }}, {{ book.could }}.\n \n+## {{ book.must }} Follow API First Principle\n+\n+As mentioned in the introduction, API First is one of our architecture principles, as per our Architecture Rules of Play. \n+In a nutshell API First has to aspects:\n+\n+- define APIs outside the code first using a standard specification language\n+- get early review feedback from peers and client developers\n+\n+By defining APIs outside the code, we want to facilitate early review feedback and also a development \n+discipline that focus service interface design on...\n+\n+- profound understanding of the domain and required functionality\n+- generalized business entities / resources — avoidance of use case specific APIs\n+- clear separation of WHAT vs. HOW concerns, i.e. abstraction from implementation aspects\n+\n+Moreover, API definitions with standardized specification format also facilitate...\n+\n+- single source of truth for API specification; \n+  it is a crucial part of a contract between service provider and client users\n+- infrastructure tooling for API discovery, API GUIs, API documents, automated quality checks\n+\n+An element of API First are also this API Guidelines and a [lightweight API review process \\[internal link\\]](https://github.bus.zalan.do/ApiGuild/ApiReviewProcedure) as to get early review feedback from peers and client developers. \n+Peer review is important for us to get high quality APIs, to enable architectural and design alignment \n+and to supported development of client applications decoupled from service provider engineering life cycle. \n+\n+It is important to learn, that API First principle is **not in conflict with the agile development principles** that we love. \n+Service applications should evolve incrementally — and so its APIs. Of course, API specification will \n+and should evolve iteratively in different cycles, each starting with draft status and early team \n+and peer review feedback. \n+\n+API may change and profit from implementation concerns and automated testing feedback. \n+API evolution during development life cycle may include breaking changes for not yet productive features \n+and as long as we have aligned the changes with the clients. \n+Hence, API First does *not* mean that you must have 100% domain and requirement understanding and can never produce code \n+before you have defined the complete API and get it confirmed by peer review. On the other hand, API First obviously is \n+in conflict with the practise of publishing API definition and asking for peer review after the service integration \n+or even the service productive operation has started. \n+It is crucial to request and get early feedback — as early as possible, unless the API changes are focussed \n+to the next evolution step and have a certain quality (including API Guideline compliance), \n+already confirmed by team internal reviews. \n+\n+\n ## {{ book.must }} Provide API Reference Definition using OpenAPI\n \n-API First is one of our architecture principles, as per our Architecture Rules of Play.\n-Define, document and review your APIs before delivering them (also see API review procedure).\n-Whether you choose YAML or JSON as a format of your OpenAPI API specification file is up to you; \n+We use [OpenAPI specification](http://swagger.io/specification/) (aka Swagger spec) as standard for our REST API definitions. \n+You may choose YAML or JSON as a format of your OpenAPI API specification file; ","path":"general-guidelines/GeneralGuidelines.md","position":52,"original_position":52,"commit_id":"208f61b919d6656c92316e9391c49c96b60e6881","original_commit_id":"208f61b919d6656c92316e9391c49c96b60e6881","user":{"login":"tfrauenstein","id":13256199,"avatar_url":"https://avatars.githubusercontent.com/u/13256199?v=3","gravatar_id":"","url":"https://api.github.com/users/tfrauenstein","html_url":"https://github.com/tfrauenstein","followers_url":"https://api.github.com/users/tfrauenstein/followers","following_url":"https://api.github.com/users/tfrauenstein/following{/other_user}","gists_url":"https://api.github.com/users/tfrauenstein/gists{/gist_id}","starred_url":"https://api.github.com/users/tfrauenstein/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tfrauenstein/subscriptions","organizations_url":"https://api.github.com/users/tfrauenstein/orgs","repos_url":"https://api.github.com/users/tfrauenstein/repos","events_url":"https://api.github.com/users/tfrauenstein/events{/privacy}","received_events_url":"https://api.github.com/users/tfrauenstein/received_events","type":"User","site_admin":false},"body":"I generally use the same wording -- correction done. ","created_at":"2016-10-11T16:30:03Z","updated_at":"2016-10-11T16:30:03Z","html_url":"https://github.com/zalando/restful-api-guidelines/pull/145#discussion_r82833703","pull_request_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145","_links":{"self":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments/82833703"},"html":{"href":"https://github.com/zalando/restful-api-guidelines/pull/145#discussion_r82833703"},"pull_request":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145"}}},"pull_request":{"url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145","id":88833852,"html_url":"https://github.com/zalando/restful-api-guidelines/pull/145","diff_url":"https://github.com/zalando/restful-api-guidelines/pull/145.diff","patch_url":"https://github.com/zalando/restful-api-guidelines/pull/145.patch","issue_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/145","number":145,"state":"open","locked":false,"title":"API First and Agility","user":{"login":"tfrauenstein","id":13256199,"avatar_url":"https://avatars.githubusercontent.com/u/13256199?v=3","gravatar_id":"","url":"https://api.github.com/users/tfrauenstein","html_url":"https://github.com/tfrauenstein","followers_url":"https://api.github.com/users/tfrauenstein/followers","following_url":"https://api.github.com/users/tfrauenstein/following{/other_user}","gists_url":"https://api.github.com/users/tfrauenstein/gists{/gist_id}","starred_url":"https://api.github.com/users/tfrauenstein/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tfrauenstein/subscriptions","organizations_url":"https://api.github.com/users/tfrauenstein/orgs","repos_url":"https://api.github.com/users/tfrauenstein/repos","events_url":"https://api.github.com/users/tfrauenstein/events{/privacy}","received_events_url":"https://api.github.com/users/tfrauenstein/received_events","type":"User","site_admin":false},"body":"Elaborate API First Principle and its relation to agile practices","created_at":"2016-10-11T13:37:44Z","updated_at":"2016-10-11T16:30:03Z","closed_at":null,"merged_at":null,"merge_commit_sha":"43decab16664484d57271de19d8e2937b566cf47","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145/commits","review_comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145/comments","review_comment_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments{/number}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/145/comments","statuses_url":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/208f61b919d6656c92316e9391c49c96b60e6881","head":{"label":"zalando:API-First-and-Agility","ref":"API-First-and-Agility","sha":"208f61b919d6656c92316e9391c49c96b60e6881","user":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"repo":{"id":55240856,"name":"restful-api-guidelines","full_name":"zalando/restful-api-guidelines","owner":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/zalando/restful-api-guidelines","description":"A model set of guidelines for RESTful APIs, created by Zalando","fork":false,"url":"https://api.github.com/repos/zalando/restful-api-guidelines","forks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/forks","keys_url":"https://api.github.com/repos/zalando/restful-api-guidelines/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zalando/restful-api-guidelines/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zalando/restful-api-guidelines/teams","hooks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/hooks","issue_events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/events{/number}","events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/events","assignees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/assignees{/user}","branches_url":"https://api.github.com/repos/zalando/restful-api-guidelines/branches{/branch}","tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/tags","blobs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/refs{/sha}","trees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/{sha}","languages_url":"https://api.github.com/repos/zalando/restful-api-guidelines/languages","stargazers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/stargazers","contributors_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contributors","subscribers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscribers","subscription_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscription","commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/commits{/sha}","git_commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/commits{/sha}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/comments{/number}","issue_comment_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/comments{/number}","contents_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contents/{+path}","compare_url":"https://api.github.com/repos/zalando/restful-api-guidelines/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zalando/restful-api-guidelines/merges","archive_url":"https://api.github.com/repos/zalando/restful-api-guidelines/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zalando/restful-api-guidelines/downloads","issues_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues{/number}","pulls_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls{/number}","milestones_url":"https://api.github.com/repos/zalando/restful-api-guidelines/milestones{/number}","notifications_url":"https://api.github.com/repos/zalando/restful-api-guidelines/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zalando/restful-api-guidelines/labels{/name}","releases_url":"https://api.github.com/repos/zalando/restful-api-guidelines/releases{/id}","deployments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/deployments","created_at":"2016-04-01T15:06:54Z","updated_at":"2016-10-11T16:05:00Z","pushed_at":"2016-10-11T15:06:00Z","git_url":"git://github.com/zalando/restful-api-guidelines.git","ssh_url":"git@github.com:zalando/restful-api-guidelines.git","clone_url":"https://github.com/zalando/restful-api-guidelines.git","svn_url":"https://github.com/zalando/restful-api-guidelines","homepage":"http://zalando.github.io/restful-api-guidelines/","size":7245,"stargazers_count":153,"watchers_count":153,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":26,"mirror_url":null,"open_issues_count":14,"forks":26,"open_issues":14,"watchers":153,"default_branch":"master"}},"base":{"label":"zalando:master","ref":"master","sha":"a019c1b94eb203777e83e1673f3dfa04ce41e692","user":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"repo":{"id":55240856,"name":"restful-api-guidelines","full_name":"zalando/restful-api-guidelines","owner":{"login":"zalando","id":1564818,"avatar_url":"https://avatars.githubusercontent.com/u/1564818?v=3","gravatar_id":"","url":"https://api.github.com/users/zalando","html_url":"https://github.com/zalando","followers_url":"https://api.github.com/users/zalando/followers","following_url":"https://api.github.com/users/zalando/following{/other_user}","gists_url":"https://api.github.com/users/zalando/gists{/gist_id}","starred_url":"https://api.github.com/users/zalando/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zalando/subscriptions","organizations_url":"https://api.github.com/users/zalando/orgs","repos_url":"https://api.github.com/users/zalando/repos","events_url":"https://api.github.com/users/zalando/events{/privacy}","received_events_url":"https://api.github.com/users/zalando/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/zalando/restful-api-guidelines","description":"A model set of guidelines for RESTful APIs, created by Zalando","fork":false,"url":"https://api.github.com/repos/zalando/restful-api-guidelines","forks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/forks","keys_url":"https://api.github.com/repos/zalando/restful-api-guidelines/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zalando/restful-api-guidelines/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zalando/restful-api-guidelines/teams","hooks_url":"https://api.github.com/repos/zalando/restful-api-guidelines/hooks","issue_events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/events{/number}","events_url":"https://api.github.com/repos/zalando/restful-api-guidelines/events","assignees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/assignees{/user}","branches_url":"https://api.github.com/repos/zalando/restful-api-guidelines/branches{/branch}","tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/tags","blobs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/refs{/sha}","trees_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/{sha}","languages_url":"https://api.github.com/repos/zalando/restful-api-guidelines/languages","stargazers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/stargazers","contributors_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contributors","subscribers_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscribers","subscription_url":"https://api.github.com/repos/zalando/restful-api-guidelines/subscription","commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/commits{/sha}","git_commits_url":"https://api.github.com/repos/zalando/restful-api-guidelines/git/commits{/sha}","comments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/comments{/number}","issue_comment_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/comments{/number}","contents_url":"https://api.github.com/repos/zalando/restful-api-guidelines/contents/{+path}","compare_url":"https://api.github.com/repos/zalando/restful-api-guidelines/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zalando/restful-api-guidelines/merges","archive_url":"https://api.github.com/repos/zalando/restful-api-guidelines/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zalando/restful-api-guidelines/downloads","issues_url":"https://api.github.com/repos/zalando/restful-api-guidelines/issues{/number}","pulls_url":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls{/number}","milestones_url":"https://api.github.com/repos/zalando/restful-api-guidelines/milestones{/number}","notifications_url":"https://api.github.com/repos/zalando/restful-api-guidelines/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zalando/restful-api-guidelines/labels{/name}","releases_url":"https://api.github.com/repos/zalando/restful-api-guidelines/releases{/id}","deployments_url":"https://api.github.com/repos/zalando/restful-api-guidelines/deployments","created_at":"2016-04-01T15:06:54Z","updated_at":"2016-10-11T16:05:00Z","pushed_at":"2016-10-11T15:06:00Z","git_url":"git://github.com/zalando/restful-api-guidelines.git","ssh_url":"git@github.com:zalando/restful-api-guidelines.git","clone_url":"https://github.com/zalando/restful-api-guidelines.git","svn_url":"https://github.com/zalando/restful-api-guidelines","homepage":"http://zalando.github.io/restful-api-guidelines/","size":7245,"stargazers_count":153,"watchers_count":153,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":26,"mirror_url":null,"open_issues_count":14,"forks":26,"open_issues":14,"watchers":153,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145"},"html":{"href":"https://github.com/zalando/restful-api-guidelines/pull/145"},"issue":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/145"},"comments":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/issues/145/comments"},"review_comments":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145/comments"},"review_comment":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/pulls/145/commits"},"statuses":{"href":"https://api.github.com/repos/zalando/restful-api-guidelines/statuses/208f61b919d6656c92316e9391c49c96b60e6881"}}}}
{"actor":{"display_login":"tfrauenstein"}}