|
| 1 | +--- |
| 2 | +title:Discovering resources for a user | GitHub API |
| 3 | +--- |
| 4 | + |
| 5 | +#Discovering resources for a user |
| 6 | + |
| 7 | +* TOC |
| 8 | +{:toc} |
| 9 | + |
| 10 | +When making authenticated requests to the GitHub API, applications often need to fetch the current user's repositories and organizations. In this guide, will explain how to reliably discover those resources. |
| 11 | + |
| 12 | +To interact with the GitHub API, we'll be using[Octokit.rb][octokit.rb]. You can find the complete source code for this project in the[platform-samples][platform samples] repository. |
| 13 | + |
| 14 | +##Getting started |
| 15 | + |
| 16 | +If you haven't already, you should read the["Basics of Authentication"][basics-of-authentication] guide before working through the examples below. The examples below assume that you have[registered an OAuth application][register-oauth-app] and that your[application has an OAuth token for a user][make-authenticated-request-for-user]. |
| 17 | + |
| 18 | +##Discover the repositories that your app can access for a user |
| 19 | + |
| 20 | +In addition to having their own personal repositories, a user may be a collaborator on repositories owned by other users and organizations. Collectively, these are the repositories where the user has privileged access: either it's a private repository where the user has read or write access, or it's a public repository where the user has write access. |
| 21 | + |
| 22 | +[OAuth scopes][scopes] determine which of those repositories your app can access for a user. Use the workflow below to discover those repositories. |
| 23 | + |
| 24 | +As always, first we'll require[GitHub's Octokit.rb][octokit.rb] Ruby library. Then we'll configure Octokit.rb to automatically handle[pagination][pagination] for us. |
| 25 | + |
| 26 | +#!ruby |
| 27 | +require 'octokit' |
| 28 | + |
| 29 | +Octokit.auto_paginate = true |
| 30 | + |
| 31 | +Next, we want to opt in to the[upcoming improvements to the repository listing API][list-repositories-for-current-user]. To do so, we'll set the media type that gives us access to that functionality. |
| 32 | + |
| 33 | +#!ruby |
| 34 | +Octokit.default_media_type = "application/vnd.github.moondragon+json" |
| 35 | + |
| 36 | +Now, we'll pass in our application's[OAuth token for a given user][make-authenticated-request-for-user]: |
| 37 | + |
| 38 | +#!ruby |
| 39 | +# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! |
| 40 | +# Instead, set and test environment variables, like below. |
| 41 | +client = Octokit::Client.new :access_token => ENV["OAUTH_ACCESS_TOKEN"] |
| 42 | + |
| 43 | +Then, we're ready to fetch the[repositories that our application can access for the user][list-repositories-for-current-user]: |
| 44 | + |
| 45 | +#!ruby |
| 46 | +client.repositories.each do |repository| |
| 47 | + full_name = repository[:full_name] |
| 48 | + has_push_access = repository[:permissions][:push] |
| 49 | + |
| 50 | + access_type = if has_push_access |
| 51 | + "write" |
| 52 | + else |
| 53 | + "read-only" |
| 54 | + end |
| 55 | + |
| 56 | + puts "User has #{access_type} access to #{full_name}." |
| 57 | +end |
| 58 | + |
| 59 | +##Discover the organizations that your app can access for a user |
| 60 | + |
| 61 | +Applications can perform all sorts of organization-related tasks for a user. To perform these tasks, the app needs an[OAuth authorization][scopes] with sufficient permission. For example, the`read:org` scope allows you to[list teams][list-teams], and the`user` scope lets you[publicize the user’s organization membership][publicize-membership]. Once a user has granted one or more of these scopes to your app, you're ready to fetch the user’s organizations. |
| 62 | + |
| 63 | +Just as we did when discovering repositories above, we'll start by requiring[GitHub's Octokit.rb][octokit.rb] Ruby library and configuring it to take care of[pagination][pagination] for us: |
| 64 | + |
| 65 | +#!ruby |
| 66 | +require 'octokit' |
| 67 | + |
| 68 | +Octokit.auto_paginate = true |
| 69 | + |
| 70 | +Next, we'll opt in to the[upcoming enhancements to the organization listing API][list-orgs-for-current-user]. To do so, we'll set the media type that gives us access to that functionality. |
| 71 | + |
| 72 | +#!ruby |
| 73 | +Octokit.default_media_type = "application/vnd.github.moondragon+json" |
| 74 | + |
| 75 | +Now, we'll pass in our application's[OAuth token for a given user][make-authenticated-request-for-user] to initialize our API client: |
| 76 | + |
| 77 | +#!ruby |
| 78 | +# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! |
| 79 | +# Instead, set and test environment variables, like below. |
| 80 | +client = Octokit::Client.new :access_token => ENV["OAUTH_ACCESS_TOKEN"] |
| 81 | + |
| 82 | +Then, we can[list the organizations that our application can access for the user][list-orgs-for-current-user]: |
| 83 | + |
| 84 | +#!ruby |
| 85 | +client.organizations.each do |organization| |
| 86 | + puts "User belongs to the #{organization[:login]} organization." |
| 87 | +end |
| 88 | + |
| 89 | +###Don’t rely on public organizations |
| 90 | + |
| 91 | +If you've read the docs from cover to cover, you may have noticed an[API method for listing a user's public organization memberships][list-public-orgs]. Most applications should avoid this API method. This method only returns the user's public organization memberships, not their private organization memberships. |
| 92 | + |
| 93 | +As an application, you typically want all of the user's organizations (public and private) that your app is authorized to access. The workflow above will give you exactly that. |
| 94 | + |
| 95 | +[basics-of-authentication]:/guides/basics-of-authentication/ |
| 96 | +[list-public-orgs]:/v3/orgs/#list-user-organizations |
| 97 | +[list-repositories-for-current-user]:/v3/repos/#list-your-repositories |
| 98 | +[list-orgs-for-current-user]:/v3/orgs/#list-your-organizations |
| 99 | +[list-teams]:/v3/orgs/teams/#list-teams |
| 100 | +[make-authenticated-request-for-user]:/guides/basics-of-authentication/#making-authenticated-requests |
| 101 | +[octokit.rb]:https://github.com/octokit/octokit.rb |
| 102 | +[pagination]:/v3/#pagination |
| 103 | +[platform samples]:https://github.com/github/platform-samples/tree/master/api/ruby/discovering-resources-for-a-user |
| 104 | +[publicize-membership]:/v3/orgs/members/#publicize-a-users-membership |
| 105 | +[register-oauth-app]:/guides/basics-of-authentication/#registering-your-app |
| 106 | +[scopes]:/v3/oauth/#scopes |