{"action":"created","comment":{"url":"https://api.github.com/repos/hashicorp/terraform-website/pulls/comments/174290734","pull_request_review_id":103617518,"id":174290734,"diff_hunk":"@@ -73,15 +71,20 @@ $ curl \\\n \n ## Add Team access to a Workspace\n \n-| Method | Path           |\n-| :----- | :------------- |\n-| POST | /team-workspaces |\n+`POST /team-workspaces`\n \n-### Parameters\n+### Request Body\n \n-- `access` (`string: <required>`) - `read`, `write`, or `admin`\n-- `team` (`string: <required>`) - The ID of the team to add to the workspace.\n-- `workspace` (`string: <required>`) - The workspace ID to which the team is to be added.\n+This POST endpoint requires a JSON object with the following properties as a request payload. (Properties without a default value are required.)\n+\n+Key path                                 | Type   | Default | Description\n+-----------------------------------------|--------|---------|------------\n+`data.type`                              | string |         | Must be `\"team-workspaces\"`.","path":"content/source/docs/enterprise/api/team-access.html.md","position":null,"original_position":38,"commit_id":"c24ccdfe9dfcabc8be9b4943492ab097ff5da5f0","original_commit_id":"c24ccdfe9dfcabc8be9b4943492ab097ff5da5f0","user":{"login":"dylanegan","id":94,"avatar_url":"https://avatars0.githubusercontent.com/u/94?v=4","gravatar_id":"","url":"https://api.github.com/users/dylanegan","html_url":"https://github.com/dylanegan","followers_url":"https://api.github.com/users/dylanegan/followers","following_url":"https://api.github.com/users/dylanegan/following{/other_user}","gists_url":"https://api.github.com/users/dylanegan/gists{/gist_id}","starred_url":"https://api.github.com/users/dylanegan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dylanegan/subscriptions","organizations_url":"https://api.github.com/users/dylanegan/orgs","repos_url":"https://api.github.com/users/dylanegan/repos","events_url":"https://api.github.com/users/dylanegan/events{/privacy}","received_events_url":"https://api.github.com/users/dylanegan/received_events","type":"User","site_admin":false},"body":"In the overview section for `JSON API` it might be worthwhile summarising these concepts. `type`, `attributes` and `relationships` are key for us and could use a sentence or two.","created_at":"2018-03-13T21:29:20Z","updated_at":"2018-03-13T21:39:11Z","html_url":"https://github.com/hashicorp/terraform-website/pull/165#discussion_r174290734","pull_request_url":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/hashicorp/terraform-website/pulls/comments/174290734"},"html":{"href":"https://github.com/hashicorp/terraform-website/pull/165#discussion_r174290734"},"pull_request":{"href":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165"}}},"pull_request":{"url":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165","id":173610224,"html_url":"https://github.com/hashicorp/terraform-website/pull/165","diff_url":"https://github.com/hashicorp/terraform-website/pull/165.diff","patch_url":"https://github.com/hashicorp/terraform-website/pull/165.patch","issue_url":"https://api.github.com/repos/hashicorp/terraform-website/issues/165","number":165,"state":"open","locked":false,"title":"Proposal for formatting API parameters","user":{"login":"nfagerlund","id":484309,"avatar_url":"https://avatars3.githubusercontent.com/u/484309?v=4","gravatar_id":"","url":"https://api.github.com/users/nfagerlund","html_url":"https://github.com/nfagerlund","followers_url":"https://api.github.com/users/nfagerlund/followers","following_url":"https://api.github.com/users/nfagerlund/following{/other_user}","gists_url":"https://api.github.com/users/nfagerlund/gists{/gist_id}","starred_url":"https://api.github.com/users/nfagerlund/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nfagerlund/subscriptions","organizations_url":"https://api.github.com/users/nfagerlund/orgs","repos_url":"https://api.github.com/users/nfagerlund/repos","events_url":"https://api.github.com/users/nfagerlund/events{/privacy}","received_events_url":"https://api.github.com/users/nfagerlund/received_events","type":"User","site_admin":false},"body":"As a reader/user, I've found it difficult to distinguish between the three types\r\nof parameters we use in our APIs. I think we can make these docs a lot more\r\nuseful by doing two things:\r\n\r\n- Explicitly separate the types of parameters (URL segments, URL query\r\nparameters, and attributes that appear in a JSON API post document) into\r\ndifferent lists. This makes the steps of assembling a valid query clearer.\r\n- Use a combination of list nesting and dot-notation to show the structure of\r\nthe JSON API document. This helps keep track of where you are while constructing\r\nthe payload, and makes the API's underlying format more visible to users who\r\naren't old hands at JSON API.\r\n\r\nI'm also adding in some missing attributes that seem to only appear in the\r\nexamples (like `type`).\r\n\r\nDylan and I are leaning toward the following guidelines for nesting vs. dot-notation:\r\n\r\n- Three levels of nesting should be the maximum just for the sake of\r\nreadability, so if any items within the `data.attributes` object have sub-items,\r\nthey should be listed with dot-notation.\r\n- If a property has only one sub-item, it should probably be listed with\r\ndot-notation.","created_at":"2018-03-08T00:09:04Z","updated_at":"2018-03-13T21:39:11Z","closed_at":null,"merged_at":null,"merge_commit_sha":"f6f90da51c4520fddd6dc5853f7f6368160f437d","assignee":null,"assignees":[],"requested_reviewers":[{"login":"davidcelis","id":36873,"avatar_url":"https://avatars3.githubusercontent.com/u/36873?v=4","gravatar_id":"","url":"https://api.github.com/users/davidcelis","html_url":"https://github.com/davidcelis","followers_url":"https://api.github.com/users/davidcelis/followers","following_url":"https://api.github.com/users/davidcelis/following{/other_user}","gists_url":"https://api.github.com/users/davidcelis/gists{/gist_id}","starred_url":"https://api.github.com/users/davidcelis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/davidcelis/subscriptions","organizations_url":"https://api.github.com/users/davidcelis/orgs","repos_url":"https://api.github.com/users/davidcelis/repos","events_url":"https://api.github.com/users/davidcelis/events{/privacy}","received_events_url":"https://api.github.com/users/davidcelis/received_events","type":"User","site_admin":false}],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165/commits","review_comments_url":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165/comments","review_comment_url":"https://api.github.com/repos/hashicorp/terraform-website/pulls/comments{/number}","comments_url":"https://api.github.com/repos/hashicorp/terraform-website/issues/165/comments","statuses_url":"https://api.github.com/repos/hashicorp/terraform-website/statuses/c24ccdfe9dfcabc8be9b4943492ab097ff5da5f0","head":{"label":"nfagerlund:mar2018_api_proposal","ref":"mar2018_api_proposal","sha":"c24ccdfe9dfcabc8be9b4943492ab097ff5da5f0","user":{"login":"nfagerlund","id":484309,"avatar_url":"https://avatars3.githubusercontent.com/u/484309?v=4","gravatar_id":"","url":"https://api.github.com/users/nfagerlund","html_url":"https://github.com/nfagerlund","followers_url":"https://api.github.com/users/nfagerlund/followers","following_url":"https://api.github.com/users/nfagerlund/following{/other_user}","gists_url":"https://api.github.com/users/nfagerlund/gists{/gist_id}","starred_url":"https://api.github.com/users/nfagerlund/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nfagerlund/subscriptions","organizations_url":"https://api.github.com/users/nfagerlund/orgs","repos_url":"https://api.github.com/users/nfagerlund/repos","events_url":"https://api.github.com/users/nfagerlund/events{/privacy}","received_events_url":"https://api.github.com/users/nfagerlund/received_events","type":"User","site_admin":false},"repo":{"id":97259236,"name":"terraform-website","full_name":"nfagerlund/terraform-website","owner":{"login":"nfagerlund","id":484309,"avatar_url":"https://avatars3.githubusercontent.com/u/484309?v=4","gravatar_id":"","url":"https://api.github.com/users/nfagerlund","html_url":"https://github.com/nfagerlund","followers_url":"https://api.github.com/users/nfagerlund/followers","following_url":"https://api.github.com/users/nfagerlund/following{/other_user}","gists_url":"https://api.github.com/users/nfagerlund/gists{/gist_id}","starred_url":"https://api.github.com/users/nfagerlund/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nfagerlund/subscriptions","organizations_url":"https://api.github.com/users/nfagerlund/orgs","repos_url":"https://api.github.com/users/nfagerlund/repos","events_url":"https://api.github.com/users/nfagerlund/events{/privacy}","received_events_url":"https://api.github.com/users/nfagerlund/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/nfagerlund/terraform-website","description":"Prototype of Terraform website being assembled from multiple repositories","fork":true,"url":"https://api.github.com/repos/nfagerlund/terraform-website","forks_url":"https://api.github.com/repos/nfagerlund/terraform-website/forks","keys_url":"https://api.github.com/repos/nfagerlund/terraform-website/keys{/key_id}","collaborators_url":"https://api.github.com/repos/nfagerlund/terraform-website/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/nfagerlund/terraform-website/teams","hooks_url":"https://api.github.com/repos/nfagerlund/terraform-website/hooks","issue_events_url":"https://api.github.com/repos/nfagerlund/terraform-website/issues/events{/number}","events_url":"https://api.github.com/repos/nfagerlund/terraform-website/events","assignees_url":"https://api.github.com/repos/nfagerlund/terraform-website/assignees{/user}","branches_url":"https://api.github.com/repos/nfagerlund/terraform-website/branches{/branch}","tags_url":"https://api.github.com/repos/nfagerlund/terraform-website/tags","blobs_url":"https://api.github.com/repos/nfagerlund/terraform-website/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/nfagerlund/terraform-website/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/nfagerlund/terraform-website/git/refs{/sha}","trees_url":"https://api.github.com/repos/nfagerlund/terraform-website/git/trees{/sha}","statuses_url":"https://api.github.com/repos/nfagerlund/terraform-website/statuses/{sha}","languages_url":"https://api.github.com/repos/nfagerlund/terraform-website/languages","stargazers_url":"https://api.github.com/repos/nfagerlund/terraform-website/stargazers","contributors_url":"https://api.github.com/repos/nfagerlund/terraform-website/contributors","subscribers_url":"https://api.github.com/repos/nfagerlund/terraform-website/subscribers","subscription_url":"https://api.github.com/repos/nfagerlund/terraform-website/subscription","commits_url":"https://api.github.com/repos/nfagerlund/terraform-website/commits{/sha}","git_commits_url":"https://api.github.com/repos/nfagerlund/terraform-website/git/commits{/sha}","comments_url":"https://api.github.com/repos/nfagerlund/terraform-website/comments{/number}","issue_comment_url":"https://api.github.com/repos/nfagerlund/terraform-website/issues/comments{/number}","contents_url":"https://api.github.com/repos/nfagerlund/terraform-website/contents/{+path}","compare_url":"https://api.github.com/repos/nfagerlund/terraform-website/compare/{base}...{head}","merges_url":"https://api.github.com/repos/nfagerlund/terraform-website/merges","archive_url":"https://api.github.com/repos/nfagerlund/terraform-website/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/nfagerlund/terraform-website/downloads","issues_url":"https://api.github.com/repos/nfagerlund/terraform-website/issues{/number}","pulls_url":"https://api.github.com/repos/nfagerlund/terraform-website/pulls{/number}","milestones_url":"https://api.github.com/repos/nfagerlund/terraform-website/milestones{/number}","notifications_url":"https://api.github.com/repos/nfagerlund/terraform-website/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/nfagerlund/terraform-website/labels{/name}","releases_url":"https://api.github.com/repos/nfagerlund/terraform-website/releases{/id}","deployments_url":"https://api.github.com/repos/nfagerlund/terraform-website/deployments","created_at":"2017-07-14T17:47:51Z","updated_at":"2017-09-15T14:02:18Z","pushed_at":"2018-03-13T18:29:04Z","git_url":"git://github.com/nfagerlund/terraform-website.git","ssh_url":"git@github.com:nfagerlund/terraform-website.git","clone_url":"https://github.com/nfagerlund/terraform-website.git","svn_url":"https://github.com/nfagerlund/terraform-website","homepage":null,"size":124395,"stargazers_count":1,"watchers_count":1,"language":"HTML","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":null,"forks":0,"open_issues":0,"watchers":1,"default_branch":"master"}},"base":{"label":"hashicorp:master","ref":"master","sha":"1941cb71235faf8b8d4a32758dd97f3c24c0fe0a","user":{"login":"hashicorp","id":761456,"avatar_url":"https://avatars2.githubusercontent.com/u/761456?v=4","gravatar_id":"","url":"https://api.github.com/users/hashicorp","html_url":"https://github.com/hashicorp","followers_url":"https://api.github.com/users/hashicorp/followers","following_url":"https://api.github.com/users/hashicorp/following{/other_user}","gists_url":"https://api.github.com/users/hashicorp/gists{/gist_id}","starred_url":"https://api.github.com/users/hashicorp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hashicorp/subscriptions","organizations_url":"https://api.github.com/users/hashicorp/orgs","repos_url":"https://api.github.com/users/hashicorp/repos","events_url":"https://api.github.com/users/hashicorp/events{/privacy}","received_events_url":"https://api.github.com/users/hashicorp/received_events","type":"Organization","site_admin":false},"repo":{"id":92349608,"name":"terraform-website","full_name":"hashicorp/terraform-website","owner":{"login":"hashicorp","id":761456,"avatar_url":"https://avatars2.githubusercontent.com/u/761456?v=4","gravatar_id":"","url":"https://api.github.com/users/hashicorp","html_url":"https://github.com/hashicorp","followers_url":"https://api.github.com/users/hashicorp/followers","following_url":"https://api.github.com/users/hashicorp/following{/other_user}","gists_url":"https://api.github.com/users/hashicorp/gists{/gist_id}","starred_url":"https://api.github.com/users/hashicorp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hashicorp/subscriptions","organizations_url":"https://api.github.com/users/hashicorp/orgs","repos_url":"https://api.github.com/users/hashicorp/repos","events_url":"https://api.github.com/users/hashicorp/events{/privacy}","received_events_url":"https://api.github.com/users/hashicorp/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/hashicorp/terraform-website","description":"Prototype of Terraform website being assembled from multiple repositories","fork":false,"url":"https://api.github.com/repos/hashicorp/terraform-website","forks_url":"https://api.github.com/repos/hashicorp/terraform-website/forks","keys_url":"https://api.github.com/repos/hashicorp/terraform-website/keys{/key_id}","collaborators_url":"https://api.github.com/repos/hashicorp/terraform-website/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/hashicorp/terraform-website/teams","hooks_url":"https://api.github.com/repos/hashicorp/terraform-website/hooks","issue_events_url":"https://api.github.com/repos/hashicorp/terraform-website/issues/events{/number}","events_url":"https://api.github.com/repos/hashicorp/terraform-website/events","assignees_url":"https://api.github.com/repos/hashicorp/terraform-website/assignees{/user}","branches_url":"https://api.github.com/repos/hashicorp/terraform-website/branches{/branch}","tags_url":"https://api.github.com/repos/hashicorp/terraform-website/tags","blobs_url":"https://api.github.com/repos/hashicorp/terraform-website/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/hashicorp/terraform-website/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/hashicorp/terraform-website/git/refs{/sha}","trees_url":"https://api.github.com/repos/hashicorp/terraform-website/git/trees{/sha}","statuses_url":"https://api.github.com/repos/hashicorp/terraform-website/statuses/{sha}","languages_url":"https://api.github.com/repos/hashicorp/terraform-website/languages","stargazers_url":"https://api.github.com/repos/hashicorp/terraform-website/stargazers","contributors_url":"https://api.github.com/repos/hashicorp/terraform-website/contributors","subscribers_url":"https://api.github.com/repos/hashicorp/terraform-website/subscribers","subscription_url":"https://api.github.com/repos/hashicorp/terraform-website/subscription","commits_url":"https://api.github.com/repos/hashicorp/terraform-website/commits{/sha}","git_commits_url":"https://api.github.com/repos/hashicorp/terraform-website/git/commits{/sha}","comments_url":"https://api.github.com/repos/hashicorp/terraform-website/comments{/number}","issue_comment_url":"https://api.github.com/repos/hashicorp/terraform-website/issues/comments{/number}","contents_url":"https://api.github.com/repos/hashicorp/terraform-website/contents/{+path}","compare_url":"https://api.github.com/repos/hashicorp/terraform-website/compare/{base}...{head}","merges_url":"https://api.github.com/repos/hashicorp/terraform-website/merges","archive_url":"https://api.github.com/repos/hashicorp/terraform-website/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/hashicorp/terraform-website/downloads","issues_url":"https://api.github.com/repos/hashicorp/terraform-website/issues{/number}","pulls_url":"https://api.github.com/repos/hashicorp/terraform-website/pulls{/number}","milestones_url":"https://api.github.com/repos/hashicorp/terraform-website/milestones{/number}","notifications_url":"https://api.github.com/repos/hashicorp/terraform-website/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/hashicorp/terraform-website/labels{/name}","releases_url":"https://api.github.com/repos/hashicorp/terraform-website/releases{/id}","deployments_url":"https://api.github.com/repos/hashicorp/terraform-website/deployments","created_at":"2017-05-25T00:53:44Z","updated_at":"2018-03-13T19:53:18Z","pushed_at":"2018-03-13T21:23:30Z","git_url":"git://github.com/hashicorp/terraform-website.git","ssh_url":"git@github.com:hashicorp/terraform-website.git","clone_url":"https://github.com/hashicorp/terraform-website.git","svn_url":"https://github.com/hashicorp/terraform-website","homepage":null,"size":124935,"stargazers_count":18,"watchers_count":18,"language":"HTML","has_issues":true,"has_projects":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":55,"mirror_url":null,"archived":false,"open_issues_count":24,"license":{"key":"other","name":"Other","spdx_id":null,"url":null},"forks":55,"open_issues":24,"watchers":18,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165"},"html":{"href":"https://github.com/hashicorp/terraform-website/pull/165"},"issue":{"href":"https://api.github.com/repos/hashicorp/terraform-website/issues/165"},"comments":{"href":"https://api.github.com/repos/hashicorp/terraform-website/issues/165/comments"},"review_comments":{"href":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165/comments"},"review_comment":{"href":"https://api.github.com/repos/hashicorp/terraform-website/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/hashicorp/terraform-website/pulls/165/commits"},"statuses":{"href":"https://api.github.com/repos/hashicorp/terraform-website/statuses/c24ccdfe9dfcabc8be9b4943492ab097ff5da5f0"}},"author_association":"COLLABORATOR"}}
{"actor":{"display_login":"dylanegan"}}