From 983f527cf581133c88c5b8c676818ad934fb8d95 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Fri, 12 Oct 2012 16:03:02 -0600 Subject: [PATCH 1/3] Document redirection behavior of api --- content/v3.md | 18 ++++++++++++++---- content/v3/orgs/members.md | 10 ++++++++++ lib/resources.rb | 2 ++ 3 files changed, 26 insertions(+), 4 deletions(-) diff --git a/content/v3.md b/content/v3.md index 1b6f543b1a..fbe260dab7 100644 --- a/content/v3.md +++ b/content/v3.md @@ -120,8 +120,19 @@ already\_exists can happen in resources that must have some unique key (such as Label names). -If resources have custom validation errors, they will be documented with -the resource. +If resources have custom validation errors, they will be documented with the resource. + +## HTTP Redirects + +API v3 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is *not* an error and clients should follow that redirect. Redirect responses will have a `Location` header field which contains the URI of the resource to which the client should repeat the requests. + +301 +: Permanent redirection. The URI you used to make the request has be superseded by the one specified in the `Location` header field. This and all future requests to this resource should be directed the new URI. + +302, 307 +: Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests. + +Other redirection status codes may be used in accordance with the HTTP 1.1 spec. ## HTTP Verbs @@ -185,7 +196,7 @@ users. ## Pagination Requests that return multiple items will be paginated to 30 items by -default. You can specify further pages with the `?page` parameter. For some +default. You can specify further pages with the `?page` parameter. For some resources, you can also set a custom page size up to 100 with the `?per_page` parameter. Note that for technical reasons not all endpoints respect the `?per_page` parameter, see [events](http://developer.github.com/v3/events/) for example. @@ -389,4 +400,3 @@ A link that looks like this: <%= json "Link" => [ ["url1", {:rel => "next"}], ["url2", {:rel => "foo", :bar => "baz"}]] %> - diff --git a/content/v3/orgs/members.md b/content/v3/orgs/members.md index 78db8bd8da..49f0a800d7 100644 --- a/content/v3/orgs/members.md +++ b/content/v3/orgs/members.md @@ -21,8 +21,14 @@ members will be returned. Otherwise only public members are returned. <%= headers 200 %> <%= json(:user) { |h| [h] } %> +### Response if requester is not a organization member + +<%= headers 302, "Location" => "https://api.github.com/orgs/github/public_members" %> + ## Get member +Check if a user is, publicly or privately, a member of the organization. + GET /orgs/:org/members/:user ### Response if user is a member @@ -33,6 +39,10 @@ members will be returned. Otherwise only public members are returned. <%= headers 404 %> +### Response if requester is not a organization member + +<%= headers 302, :Location => "https://api.github.com/orgs/github/public_members/pezra" %> + ## Add a member To add someone as a member to an org, you must add them to a diff --git a/lib/resources.rb b/lib/resources.rb index cb75d77ec5..6c997f2227 100644 --- a/lib/resources.rb +++ b/lib/resources.rb @@ -12,6 +12,8 @@ module Helpers 202 => '202 Accepted', 204 => '204 No Content', 301 => '301 Moved Permanently', + 302 => '302 Found', + 307 => '307 Temporary Redirect', 304 => '304 Not Modified', 401 => '401 Unauthorized', 403 => '403 Forbidden', From de55dd9809a1d6bbc229a0b834550705c6dba87e Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Sat, 13 Oct 2012 17:05:18 -0600 Subject: [PATCH 2/3] Updated members page and added a changes entry to reflect github/github#6584 --- .../2012-10-12-org-members-redirection.md | 10 ++++++++ content/v3/orgs/members.md | 24 ++++++++++--------- 2 files changed, 23 insertions(+), 11 deletions(-) create mode 100644 content/changes/2012-10-12-org-members-redirection.md diff --git a/content/changes/2012-10-12-org-members-redirection.md b/content/changes/2012-10-12-org-members-redirection.md new file mode 100644 index 0000000000..c08c1fa63b --- /dev/null +++ b/content/changes/2012-10-12-org-members-redirection.md @@ -0,0 +1,10 @@ +--- +kind: change +title: Organization Members Resource Changes +created_at: 2012-10-12 +author_name: pezra +--- + +Requesting the [member list](/v3/orgs/members/index.html#members-list) of an organization of which you are not a member now redirects to the [public members list](v3/orgs/members/index.html#public-members-list). Requests to [membership check](/v3/orgs/members/index.html#check-membership) resources of an organization of which you are not a member are similarly redirected to the equivalent [public membership check](/v3/orgs/members/index.html#check-public-membership) unless it is a check about yourself, in which case it is treated as a request by a member. + +The changes where made to clarify the purpose of these various resources. The `/orgs/{org}/members` resources are intended for use by members of the organization in question. The `/orgs/{org}/public_members` resources are intended for acquiring information about organizations of which you are not a member. diff --git a/content/v3/orgs/members.md b/content/v3/orgs/members.md index 49f0a800d7..7931b358e4 100644 --- a/content/v3/orgs/members.md +++ b/content/v3/orgs/members.md @@ -7,12 +7,10 @@ title: Organization Members | GitHub API * TOC {:toc} -## List members +## Members list List all users who are members of an organization. A member is a user -that belongs to at least 1 team in the organization. If the authenticated user is -also a member of this organization then both concealed and public -members will be returned. Otherwise only public members are returned. +that belongs to at least 1 team in the organization. If the authenticated user is also a member of this organization then both concealed and public members will be returned. If the reqeuster is not a member of the organization the query will be redirected to the [public members list](#public-members-list). GET /orgs/:org/members @@ -21,25 +19,29 @@ members will be returned. Otherwise only public members are returned. <%= headers 200 %> <%= json(:user) { |h| [h] } %> -### Response if requester is not a organization member +### Response if requester is not an organization member <%= headers 302, "Location" => "https://api.github.com/orgs/github/public_members" %> -## Get member +## Check membership Check if a user is, publicly or privately, a member of the organization. GET /orgs/:org/members/:user -### Response if user is a member +### Response if requester is an organization member and user is a member <%= headers 204 %> -### Response if user is not a member +### Response if requester is an organization member and user is not a member <%= headers 404 %> -### Response if requester is not a organization member +### Response if requester is not an organization member and is inquiring about themselves + +<%= headers 404 %> + +### Response if requester is not an organization member <%= headers 302, :Location => "https://api.github.com/orgs/github/public_members/pezra" %> @@ -59,7 +61,7 @@ they will no longer have any access to the organization's repositories. <%= headers 204 %> -## List public members +## Public members list Members of an organization can choose to have their membership publicized or not. @@ -71,7 +73,7 @@ publicized or not. <%= headers 200 %> <%= json(:user) { |h| [h] } %> -## Get if a user is a public member +## Check public membership GET /orgs/:org/public_members/:user From 5612df8a5887180bdff140fa727c4bf0a0e867d1 Mon Sep 17 00:00:00 2001 From: Peter Williams Date: Mon, 15 Oct 2012 12:40:20 -0600 Subject: [PATCH 3/3] Add my gravatar id --- lib/resources.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/resources.rb b/lib/resources.rb index 6c997f2227..d014b2e8ed 100644 --- a/lib/resources.rb +++ b/lib/resources.rb @@ -25,7 +25,8 @@ module Helpers AUTHORS = { :technoweenie => '821395fe70906c8290df7f18ac4ac6cf', - :pengwynn => '7e19cd5486b5d6dc1ef90e671ba52ae0' + :pengwynn => '7e19cd5486b5d6dc1ef90e671ba52ae0', + :pezra => 'f38112009dc16547051c8ac246cee443' } DefaultTimeFormat = "%B %-d, %Y".freeze