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.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..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,18 +19,32 @@ members will be returned. Otherwise only public members are returned. <%= headers 200 %> <%= json(:user) { |h| [h] } %> -## Get member +### Response if requester is not an organization member + +<%= headers 302, "Location" => "https://api.github.com/orgs/github/public_members" %> + +## 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 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" %> + ## Add a member To add someone as a member to an org, you must add them to a @@ -49,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. @@ -61,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 diff --git a/lib/resources.rb b/lib/resources.rb index cb75d77ec5..d014b2e8ed 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', @@ -23,7 +25,8 @@ module Helpers AUTHORS = { :technoweenie => '821395fe70906c8290df7f18ac4ac6cf', - :pengwynn => '7e19cd5486b5d6dc1ef90e671ba52ae0' + :pengwynn => '7e19cd5486b5d6dc1ef90e671ba52ae0', + :pezra => 'f38112009dc16547051c8ac246cee443' } DefaultTimeFormat = "%B %-d, %Y".freeze