{"action":"opened","number":195,"pull_request":{"url":"https://api.github.com/repos/opencfp/opencfp/pulls/195","id":35428642,"html_url":"https://github.com/opencfp/opencfp/pull/195","diff_url":"https://github.com/opencfp/opencfp/pull/195.diff","patch_url":"https://github.com/opencfp/opencfp/pull/195.patch","issue_url":"https://api.github.com/repos/opencfp/opencfp/issues/195","number":195,"state":"open","locked":false,"title":"[WIP] Discussion on API Documentation","user":{"login":"mdwheele","id":2453394,"avatar_url":"https://avatars.githubusercontent.com/u/2453394?v=3","gravatar_id":"","url":"https://api.github.com/users/mdwheele","html_url":"https://github.com/mdwheele","followers_url":"https://api.github.com/users/mdwheele/followers","following_url":"https://api.github.com/users/mdwheele/following{/other_user}","gists_url":"https://api.github.com/users/mdwheele/gists{/gist_id}","starred_url":"https://api.github.com/users/mdwheele/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mdwheele/subscriptions","organizations_url":"https://api.github.com/users/mdwheele/orgs","repos_url":"https://api.github.com/users/mdwheele/repos","events_url":"https://api.github.com/users/mdwheele/events{/privacy}","received_events_url":"https://api.github.com/users/mdwheele/received_events","type":"User","site_admin":false},"body":"**Do not merge**\r\n\r\nI'm submitting this as a line of work on a first iteration of API documentation. I will be merging this into the implementation branch once finalized. \r\n\r\nThe point of this is to put an overview in front of folks of how all of this will fit together. I'm looking to pare this down a bit as I feel it is wordy and, in places, justifies implementation details rather than just saying, \"This is how the shit works.\" for users to consume. Please rip it apart on those terms.\r\n\r\nThat said, it also suggests a rough technical direction for the API and there are some assumptions being made, for sure. I wish for those to be challenged / questioned where appropriate. Things that come to mind:\r\n\r\n1. We're implementing client registration in compliance with the current [OAuth 2.0 Dynamic Client Registration Protocol](https://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-23) draft. This means that we're able to move to a full implementation later, but what we're allowing (at this point) is for any arbitrary web application / client to register client application on any instance of OpenCFP where the API is enabled. There is no approval process. This is a trade-off. On the one hand, it is MUCH simpler to implement for a consuming application as there is no need for a pre-arranged access token / handshake. On the other hand, it leaves an instance of OpenCFP open for exploitation; where the \"exploit\" is the ability to create infinite client applications. We can actually take measures against this as a compensating control without penalizing nice users. Just don't want to be driven by FUD here, because it is very convenient, as described currently. Also note that simply \"having a client application\" buys the application nothing. They will still need to put users through an authorization flow before receiving tokens to do anything.\r\n2. I make assumptions on what is valuable to a consumer as part of the API. This should be challenged by potential consumers.\r\n\r\nI may add to this. I'm on a break and on-the-move.","created_at":"2015-05-14T14:57:31Z","updated_at":"2015-05-14T14:57:31Z","closed_at":null,"merged_at":null,"merge_commit_sha":null,"assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/opencfp/opencfp/pulls/195/commits","review_comments_url":"https://api.github.com/repos/opencfp/opencfp/pulls/195/comments","review_comment_url":"https://api.github.com/repos/opencfp/opencfp/pulls/comments{/number}","comments_url":"https://api.github.com/repos/opencfp/opencfp/issues/195/comments","statuses_url":"https://api.github.com/repos/opencfp/opencfp/statuses/d5152aa140ccc3df421519a95741c5cc45016e55","head":{"label":"mdwheele:json-api-docs","ref":"json-api-docs","sha":"d5152aa140ccc3df421519a95741c5cc45016e55","user":{"login":"mdwheele","id":2453394,"avatar_url":"https://avatars.githubusercontent.com/u/2453394?v=3","gravatar_id":"","url":"https://api.github.com/users/mdwheele","html_url":"https://github.com/mdwheele","followers_url":"https://api.github.com/users/mdwheele/followers","following_url":"https://api.github.com/users/mdwheele/following{/other_user}","gists_url":"https://api.github.com/users/mdwheele/gists{/gist_id}","starred_url":"https://api.github.com/users/mdwheele/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mdwheele/subscriptions","organizations_url":"https://api.github.com/users/mdwheele/orgs","repos_url":"https://api.github.com/users/mdwheele/repos","events_url":"https://api.github.com/users/mdwheele/events{/privacy}","received_events_url":"https://api.github.com/users/mdwheele/received_events","type":"User","site_admin":false},"repo":{"id":24079693,"name":"opencfp","full_name":"mdwheele/opencfp","owner":{"login":"mdwheele","id":2453394,"avatar_url":"https://avatars.githubusercontent.com/u/2453394?v=3","gravatar_id":"","url":"https://api.github.com/users/mdwheele","html_url":"https://github.com/mdwheele","followers_url":"https://api.github.com/users/mdwheele/followers","following_url":"https://api.github.com/users/mdwheele/following{/other_user}","gists_url":"https://api.github.com/users/mdwheele/gists{/gist_id}","starred_url":"https://api.github.com/users/mdwheele/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mdwheele/subscriptions","organizations_url":"https://api.github.com/users/mdwheele/orgs","repos_url":"https://api.github.com/users/mdwheele/repos","events_url":"https://api.github.com/users/mdwheele/events{/privacy}","received_events_url":"https://api.github.com/users/mdwheele/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/mdwheele/opencfp","description":"Repo for OpenCFP project, a PHP-based conference talk submission system","fork":true,"url":"https://api.github.com/repos/mdwheele/opencfp","forks_url":"https://api.github.com/repos/mdwheele/opencfp/forks","keys_url":"https://api.github.com/repos/mdwheele/opencfp/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mdwheele/opencfp/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mdwheele/opencfp/teams","hooks_url":"https://api.github.com/repos/mdwheele/opencfp/hooks","issue_events_url":"https://api.github.com/repos/mdwheele/opencfp/issues/events{/number}","events_url":"https://api.github.com/repos/mdwheele/opencfp/events","assignees_url":"https://api.github.com/repos/mdwheele/opencfp/assignees{/user}","branches_url":"https://api.github.com/repos/mdwheele/opencfp/branches{/branch}","tags_url":"https://api.github.com/repos/mdwheele/opencfp/tags","blobs_url":"https://api.github.com/repos/mdwheele/opencfp/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mdwheele/opencfp/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mdwheele/opencfp/git/refs{/sha}","trees_url":"https://api.github.com/repos/mdwheele/opencfp/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mdwheele/opencfp/statuses/{sha}","languages_url":"https://api.github.com/repos/mdwheele/opencfp/languages","stargazers_url":"https://api.github.com/repos/mdwheele/opencfp/stargazers","contributors_url":"https://api.github.com/repos/mdwheele/opencfp/contributors","subscribers_url":"https://api.github.com/repos/mdwheele/opencfp/subscribers","subscription_url":"https://api.github.com/repos/mdwheele/opencfp/subscription","commits_url":"https://api.github.com/repos/mdwheele/opencfp/commits{/sha}","git_commits_url":"https://api.github.com/repos/mdwheele/opencfp/git/commits{/sha}","comments_url":"https://api.github.com/repos/mdwheele/opencfp/comments{/number}","issue_comment_url":"https://api.github.com/repos/mdwheele/opencfp/issues/comments{/number}","contents_url":"https://api.github.com/repos/mdwheele/opencfp/contents/{+path}","compare_url":"https://api.github.com/repos/mdwheele/opencfp/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mdwheele/opencfp/merges","archive_url":"https://api.github.com/repos/mdwheele/opencfp/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mdwheele/opencfp/downloads","issues_url":"https://api.github.com/repos/mdwheele/opencfp/issues{/number}","pulls_url":"https://api.github.com/repos/mdwheele/opencfp/pulls{/number}","milestones_url":"https://api.github.com/repos/mdwheele/opencfp/milestones{/number}","notifications_url":"https://api.github.com/repos/mdwheele/opencfp/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mdwheele/opencfp/labels{/name}","releases_url":"https://api.github.com/repos/mdwheele/opencfp/releases{/id}","created_at":"2014-09-16T00:46:40Z","updated_at":"2015-03-07T22:43:14Z","pushed_at":"2015-05-14T14:45:10Z","git_url":"git://github.com/mdwheele/opencfp.git","ssh_url":"git@github.com:mdwheele/opencfp.git","clone_url":"https://github.com/mdwheele/opencfp.git","svn_url":"https://github.com/mdwheele/opencfp","homepage":null,"size":2349,"stargazers_count":0,"watchers_count":0,"language":"PHP","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":"opencfp:master","ref":"master","sha":"10541b9ad65da08b4dcf6ac7b3fb90b0a26bed57","user":{"login":"opencfp","id":4657079,"avatar_url":"https://avatars.githubusercontent.com/u/4657079?v=3","gravatar_id":"","url":"https://api.github.com/users/opencfp","html_url":"https://github.com/opencfp","followers_url":"https://api.github.com/users/opencfp/followers","following_url":"https://api.github.com/users/opencfp/following{/other_user}","gists_url":"https://api.github.com/users/opencfp/gists{/gist_id}","starred_url":"https://api.github.com/users/opencfp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opencfp/subscriptions","organizations_url":"https://api.github.com/users/opencfp/orgs","repos_url":"https://api.github.com/users/opencfp/repos","events_url":"https://api.github.com/users/opencfp/events{/privacy}","received_events_url":"https://api.github.com/users/opencfp/received_events","type":"Organization","site_admin":false},"repo":{"id":9820191,"name":"opencfp","full_name":"opencfp/opencfp","owner":{"login":"opencfp","id":4657079,"avatar_url":"https://avatars.githubusercontent.com/u/4657079?v=3","gravatar_id":"","url":"https://api.github.com/users/opencfp","html_url":"https://github.com/opencfp","followers_url":"https://api.github.com/users/opencfp/followers","following_url":"https://api.github.com/users/opencfp/following{/other_user}","gists_url":"https://api.github.com/users/opencfp/gists{/gist_id}","starred_url":"https://api.github.com/users/opencfp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/opencfp/subscriptions","organizations_url":"https://api.github.com/users/opencfp/orgs","repos_url":"https://api.github.com/users/opencfp/repos","events_url":"https://api.github.com/users/opencfp/events{/privacy}","received_events_url":"https://api.github.com/users/opencfp/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/opencfp/opencfp","description":"Repo for OpenCFP project, a PHP-based conference talk submission system","fork":false,"url":"https://api.github.com/repos/opencfp/opencfp","forks_url":"https://api.github.com/repos/opencfp/opencfp/forks","keys_url":"https://api.github.com/repos/opencfp/opencfp/keys{/key_id}","collaborators_url":"https://api.github.com/repos/opencfp/opencfp/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/opencfp/opencfp/teams","hooks_url":"https://api.github.com/repos/opencfp/opencfp/hooks","issue_events_url":"https://api.github.com/repos/opencfp/opencfp/issues/events{/number}","events_url":"https://api.github.com/repos/opencfp/opencfp/events","assignees_url":"https://api.github.com/repos/opencfp/opencfp/assignees{/user}","branches_url":"https://api.github.com/repos/opencfp/opencfp/branches{/branch}","tags_url":"https://api.github.com/repos/opencfp/opencfp/tags","blobs_url":"https://api.github.com/repos/opencfp/opencfp/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/opencfp/opencfp/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/opencfp/opencfp/git/refs{/sha}","trees_url":"https://api.github.com/repos/opencfp/opencfp/git/trees{/sha}","statuses_url":"https://api.github.com/repos/opencfp/opencfp/statuses/{sha}","languages_url":"https://api.github.com/repos/opencfp/opencfp/languages","stargazers_url":"https://api.github.com/repos/opencfp/opencfp/stargazers","contributors_url":"https://api.github.com/repos/opencfp/opencfp/contributors","subscribers_url":"https://api.github.com/repos/opencfp/opencfp/subscribers","subscription_url":"https://api.github.com/repos/opencfp/opencfp/subscription","commits_url":"https://api.github.com/repos/opencfp/opencfp/commits{/sha}","git_commits_url":"https://api.github.com/repos/opencfp/opencfp/git/commits{/sha}","comments_url":"https://api.github.com/repos/opencfp/opencfp/comments{/number}","issue_comment_url":"https://api.github.com/repos/opencfp/opencfp/issues/comments{/number}","contents_url":"https://api.github.com/repos/opencfp/opencfp/contents/{+path}","compare_url":"https://api.github.com/repos/opencfp/opencfp/compare/{base}...{head}","merges_url":"https://api.github.com/repos/opencfp/opencfp/merges","archive_url":"https://api.github.com/repos/opencfp/opencfp/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/opencfp/opencfp/downloads","issues_url":"https://api.github.com/repos/opencfp/opencfp/issues{/number}","pulls_url":"https://api.github.com/repos/opencfp/opencfp/pulls{/number}","milestones_url":"https://api.github.com/repos/opencfp/opencfp/milestones{/number}","notifications_url":"https://api.github.com/repos/opencfp/opencfp/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/opencfp/opencfp/labels{/name}","releases_url":"https://api.github.com/repos/opencfp/opencfp/releases{/id}","created_at":"2013-05-02T18:50:26Z","updated_at":"2015-05-13T11:24:01Z","pushed_at":"2015-05-13T13:54:59Z","git_url":"git://github.com/opencfp/opencfp.git","ssh_url":"git@github.com:opencfp/opencfp.git","clone_url":"https://github.com/opencfp/opencfp.git","svn_url":"https://github.com/opencfp/opencfp","homepage":null,"size":3349,"stargazers_count":100,"watchers_count":100,"language":"PHP","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":49,"mirror_url":null,"open_issues_count":12,"forks":49,"open_issues":12,"watchers":100,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/opencfp/opencfp/pulls/195"},"html":{"href":"https://github.com/opencfp/opencfp/pull/195"},"issue":{"href":"https://api.github.com/repos/opencfp/opencfp/issues/195"},"comments":{"href":"https://api.github.com/repos/opencfp/opencfp/issues/195/comments"},"review_comments":{"href":"https://api.github.com/repos/opencfp/opencfp/pulls/195/comments"},"review_comment":{"href":"https://api.github.com/repos/opencfp/opencfp/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/opencfp/opencfp/pulls/195/commits"},"statuses":{"href":"https://api.github.com/repos/opencfp/opencfp/statuses/d5152aa140ccc3df421519a95741c5cc45016e55"}},"merged":false,"mergeable":null,"mergeable_state":"unknown","merged_by":null,"comments":0,"review_comments":0,"commits":10,"additions":306,"deletions":0,"changed_files":1}}