Skip to content

Commit dea96de

Browse files
tobiasahlintobiasahlin
committed
Merge master
2 parents 490c71e + 99b8e2a commit dea96de

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+352
-290
lines changed

‎Rules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ end
4444
compile '/guides/*' do
4545
filter :kramdown, :toc_levels => [2]
4646
filter :erb
47+
filter :colorize_syntax, :default_colorizer => :pygmentsrb
4748
layout item[:layout] || 'guides'
4849
end
4950

‎content/changes/2013-10-04-oauth-changes-coming.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
For example, if you are making a POST with the `application/json`
1111
mime-type you'll see an additional field for the granted scopes.
1212

13-
<pre class="highlight"><code class="language-javascript">
13+
<pre><code class="language-javascript">
1414
{
1515
"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a",
1616
"scope":"repo,gist",

‎content/guides/basics-of-authentication.md‎

Lines changed: 31 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,33 @@ title: Basics of Authentication | GitHub API
77
* TOC
88
{:toc}
99

10-
In this section, we're going to focus on the basics of authentication. Specifically,
11-
we're going to create a Ruby server (using [Sinatra][Sinatra]) that implements
10+
In this section, we're going to focus on the basics of authentication. Specifically,
11+
we're going to create a Ruby server (using [Sinatra][Sinatra]) that implements
1212
the [web flow][webflow] of an application in several different ways.
1313

1414
Note: you can download the complete source code for this project [from the platform-samples repo](https://github.com/github/platform-samples/tree/master/api/ruby/basics-of-authentication).
1515

1616
## Registering your app
1717

1818
First, you'll need to [register your
19-
application](https://github.com/settings/applications/new). Every
20-
registered OAuth application is assigned a unique Client ID and Client Secret.
19+
application](https://github.com/settings/applications/new). Every
20+
registered OAuth application is assigned a unique Client ID and Client Secret.
2121
The Client Secret should not be shared! That includes checking the string
2222
into your repository.
2323

24-
You can fill out every piece of information however you like, except the
25-
**Authorization callback URL**. This is easily the most important piece to setting
26-
up your application. It's the callback URL that GitHub returns the user to after
24+
You can fill out every piece of information however you like, except the
25+
**Authorization callback URL**. This is easily the most important piece to setting
26+
up your application. It's the callback URL that GitHub returns the user to after
2727
successful authentication.
2828

29-
Since we're running a regular Sinatra server, the location of the local instance
29+
Since we're running a regular Sinatra server, the location of the local instance
3030
is set to `http://localhost:4567`. Let's fill in the callback URL as `http://localhost:4567/callback`.
3131

3232
## Accepting user authorization
3333

3434
Now, let's start filling out our simple server. Create a file called _server.rb_ and paste this into it:
3535

36+
#!ruby
3637
require 'sinatra'
3738
require 'rest-client'
3839

@@ -43,42 +44,43 @@ Now, let's start filling out our simple server. Create a file called _server.rb_
4344
erb :index, :locals => {:client_id => CLIENT_ID}
4445
end
4546

46-
Your client ID and client secret keys come from [your application's configuration page](https://github.com/settings/applications). You should **never, _ever_** store these values in
47+
Your client ID and client secret keys come from [your application's configuration page](https://github.com/settings/applications). You should **never, _ever_** store these values in
4748
GitHub--or any other public place, for that matter. We recommend storing them as
4849
[environment variables][about env vars]--which is exactly what we've done here.
4950

5051
Next, in _views/index.erb_, paste this content:
5152

52-
53+
#!html+erb
5354
<html>
5455
<head>
5556
</head>
5657
<body>
5758
<p>Well, hello there!</p>
5859
<p>We're going to now talk to the GitHub API. Ready? <a href="https://github.com/login/oauth/authorize?client_id=<%= client_id %>">Click here</a> to begin!</a></p>
59-
<p>If that link doesn't work, remember to provide your own <a href="http://developer.github.com/v3/oauth/#web-application-flow">Client ID</a>!</p>
60+
<p>If that link doesn't work, remember to provide your own <a href="/v3/oauth/#web-application-flow">Client ID</a>!</p>
6061
</body>
6162
</html>
6263

6364
(If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra guide].)
6465

65-
Obviously, you'll want to change `<your_client_id>` to match your actual Client ID.
66+
Obviously, you'll want to change `<your_client_id>` to match your actual Client ID.
6667

67-
Navigate your browser to `http://localhost:4567`. After clicking on the link, you
68+
Navigate your browser to `http://localhost:4567`. After clicking on the link, you
6869
should be taken to GitHub, and presented with a dialog that looks something like this:
6970
![](/images/oauth_prompt.png)
7071

71-
If you trust yourself, click **Authorize App**. Wuh-oh! Sinatra spits out a
72+
If you trust yourself, click **Authorize App**. Wuh-oh! Sinatra spits out a
7273
`404` error. What gives?!
7374

7475
Well, remember when we specified a Callback URL to be `callback`? We didn't provide
75-
a route for it, so GitHub doesn't know where to drop the user after they authorize
76+
a route for it, so GitHub doesn't know where to drop the user after they authorize
7677
the app. Let's fix that now!
7778

7879
### Providing a callback
7980

8081
In _server.rb_, add a route to specify what the callback should do:
8182

83+
#!ruby
8284
get '/callback' do
8385
# get temporary GitHub code...
8486
session_code = request.env['rack.request.query_hash']["code"]
@@ -94,20 +96,22 @@ In _server.rb_, add a route to specify what the callback should do:
9496
end
9597

9698
After a successful app authentication, GitHub provides a temporary `code` value.
97-
You'll need to `POST` this code back to GitHub in exchange for an `access_token`.
99+
You'll need to `POST` this code back to GitHub in exchange for an `access_token`.
98100
To simplify our GET and POST HTTP requests, we're using the [rest-client][REST Client].
99-
Note that you'll probably never access the API through REST. For a more serious
101+
Note that you'll probably never access the API through REST. For a more serious
100102
application, you should probably use [a library written in the language of your choice][libraries].
101103

102104
At last, with this access token, you'll be able to make authenticated requests as
103105
the logged in user:
104106

107+
#!ruby
105108
auth_result = RestClient.get("https://api.github.com/user", {:params => {:access_token => access_token}})
106109

107110
erb :basic, :locals => {:auth_result => auth_result}
108111

109112
We can do whatever we want with our results. In this case, we'll just dump them straight into _basic.erb_:
110113

114+
#!html+erb
111115
<p>Okay, here's a JSON dump:</p>
112116
<p>
113117
<p>Hello, <%= login %>! It looks like you're <%= hire_status %>.</p>
@@ -116,12 +120,12 @@ We can do whatever we want with our results. In this case, we'll just dump them
116120
## Implementing "persistent" authentication
117121

118122
It'd be a pretty bad model if we required users to log into the app every single
119-
time they needed to access the web page. For example, try navigating directly to
123+
time they needed to access the web page. For example, try navigating directly to
120124
`http://localhost:4567/basic`. You'll get an error.
121125

122126
What if we could circumvent the entire
123127
"click here" process, and just _remember_ that, as long as the user's logged into
124-
GitHub, they should be able to access this application? Hold on to your hat,
128+
GitHub, they should be able to access this application? Hold on to your hat,
125129
because _that's exactly what we're going to do_.
126130

127131
Our little server above is rather simple. In order to wedge in some intelligent
@@ -133,6 +137,7 @@ This will make authentication transparent to the user.
133137
After you run `gem install sinatra_auth_github`, create a file called _advanced_server.rb_,
134138
and paste these lines into it:
135139

140+
#!ruby
136141
require 'sinatra/auth/github'
137142
require 'rest-client'
138143

@@ -164,7 +169,7 @@ and paste these lines into it:
164169
authenticate!
165170
else
166171
access_token = github_user["token"]
167-
auth_result = RestClient.get("https://api.github.com/user", {:params => {:access_token => access_token, :accept => :json},
172+
auth_result = RestClient.get("https://api.github.com/user", {:params => {:access_token => access_token, :accept => :json},
168173
:accept => :json})
169174

170175
auth_result = JSON.parse(auth_result)
@@ -184,14 +189,14 @@ and paste these lines into it:
184189
end
185190
end
186191

187-
Much of the code should look familiar. For example, we're still using `RestClient.get`
192+
Much of the code should look familiar. For example, we're still using `RestClient.get`
188193
to call out to the GitHub API, and we're still passing our results to be rendered
189194
in an ERB template (this time, it's called `advanced.erb`). Some of the other
190195
details--like turning our app into a class that inherits from `Sinatra::Base`--are a result
191196
of inheriting from `sinatra/auth/github`, which is written as [a Sinatra extension][sinatra extension].
192197

193198
Also, we now have a `github_user` object, which comes from `sinatra-auth-github`. The
194-
`token` key represents the same `access_token` we used during our simple server.
199+
`token` key represents the same `access_token` we used during our simple server.
195200

196201
`sinatra-auth-github` comes with quite a few options that you can customize. Here,
197202
we're establishing them through the `:github_options` symbol. Passing your client ID
@@ -201,6 +206,7 @@ to simplify your authentication.
201206
We must also create a _config.ru_ config file, which Rack will use for its configuration
202207
options:
203208

209+
#!ruby
204210
ENV['RACK_ENV'] ||= 'development'
205211
require "rubygems"
206212
require "bundler/setup"
@@ -211,6 +217,7 @@ options:
211217

212218
Next, create a file in _views_ called _advanced.erb_, and paste this markup into it:
213219

220+
#!html+erb
214221
<html>
215222
<head>
216223
</head>
@@ -235,12 +242,12 @@ we would've seen the same confirmation dialog from earlier pop-up and warn us.
235242
If you'd like, you can play around with [yet another Sinatra-GitHub auth example][sinatra auth github test]
236243
available as a separate project.
237244

238-
[webflow]: http://developer.github.com/v3/oauth/#web-application-flow
245+
[webflow]: /v3/oauth/#web-application-flow
239246
[Sinatra]: http://www.sinatrarb.com/
240247
[about env vars]: http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables
241248
[Sinatra guide]: http://sinatra-book.gittr.com/#hello_world_application
242249
[REST Client]: https://github.com/archiloque/rest-client
243-
[libraries]: http://developer.github.com/v3/libraries/
250+
[libraries]: /libraries/
244251
[rack guide]: http://en.wikipedia.org/wiki/Rack_(web_server_interface)
245252
[sinatra auth github]: https://github.com/atmos/sinatra_auth_github
246253
[sinatra extension]: http://www.sinatrarb.com/extensions.html

‎content/guides/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -444,7 +444,7 @@ responses don't count against your [rate limit][rate-limiting].
444444

445445

446446

447-
[wrappers]: http://developer.github.com/v3/libraries/
447+
[wrappers]: http://developer.github.com/libraries/
448448
[curl]: http://curl.haxx.se/
449449
[media types]: http://developer.github.com/v3/media/
450450
[oauth]: http://developer.github.com/v3/oauth/

‎content/guides/rendering-data-as-graphs.md‎

Lines changed: 47 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -23,43 +23,45 @@ First, [register a new application][new oauth application] on GitHub. Set the ma
2323
URLs to `http://localhost:4567/`. As [before][basics-of-authentication], we're going to handle authentication for the API by
2424
implementing a Rack middleware using [sinatra-auth-github][sinatra auth github]:
2525

26-
require 'sinatra/auth/github'
27-
28-
module Example
29-
class MyGraphApp < Sinatra::Base
30-
# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!!
31-
# Instead, set and test environment variables, like below
32-
# if ENV['GITHUB_CLIENT_ID'] && ENV['GITHUB_CLIENT_SECRET']
33-
# CLIENT_ID = ENV['GITHUB_CLIENT_ID']
34-
# CLIENT_SECRET = ENV['GITHUB_CLIENT_SECRET']
35-
# end
36-
37-
CLIENT_ID = ENV['GH_GRAPH_CLIENT_ID']
38-
CLIENT_SECRET = ENV['GH_GRAPH_SECRET_ID']
39-
40-
enable :sessions
41-
42-
set :github_options, {
43-
:scopes => "repo",
44-
:secret => CLIENT_SECRET,
45-
:client_id => CLIENT_ID,
46-
:callback_url => "/"
47-
}
48-
49-
register Sinatra::Auth::Github
50-
51-
get '/' do
52-
if !authenticated?
53-
authenticate!
54-
else
55-
access_token = github_user["token"]
56-
end
57-
end
58-
end
59-
end
26+
#!ruby
27+
require 'sinatra/auth/github'
28+
29+
module Example
30+
class MyGraphApp < Sinatra::Base
31+
# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!!
32+
# Instead, set and test environment variables, like below
33+
# if ENV['GITHUB_CLIENT_ID'] && ENV['GITHUB_CLIENT_SECRET']
34+
# CLIENT_ID = ENV['GITHUB_CLIENT_ID']
35+
# CLIENT_SECRET = ENV['GITHUB_CLIENT_SECRET']
36+
# end
37+
38+
CLIENT_ID = ENV['GH_GRAPH_CLIENT_ID']
39+
CLIENT_SECRET = ENV['GH_GRAPH_SECRET_ID']
40+
41+
enable :sessions
42+
43+
set :github_options, {
44+
:scopes => "repo",
45+
:secret => CLIENT_SECRET,
46+
:client_id => CLIENT_ID,
47+
:callback_url => "/"
48+
}
49+
50+
register Sinatra::Auth::Github
51+
52+
get '/' do
53+
if !authenticated?
54+
authenticate!
55+
else
56+
access_token = github_user["token"]
57+
end
58+
end
59+
end
60+
end
6061

6162
Set up a similar _config.ru_ file as in the previous example:
6263

64+
#!ruby
6365
ENV['RACK_ENV'] ||= 'development'
6466
require "rubygems"
6567
require "bundler/setup"
@@ -78,6 +80,7 @@ so you know it'll work.
7880
Authentication with the API via Octokit is easy. Just pass your login
7981
and token to the `Octokit::Client` constructor:
8082

83+
#!ruby
8184
if !authenticated?
8285
authenticate!
8386
else
@@ -89,11 +92,13 @@ to see the different programming languages they use, and count which ones are us
8992
most often. To do that, we'll first need a list of our repositories from the API.
9093
With Octokit, that looks like this:
9194

95+
#!ruby
9296
repos = client.repositories
9397

9498
Next, we'll iterate over each repository, and count the language that GitHub
9599
associates with it:
96100

101+
#!ruby
97102
language_obj = {}
98103
repos.each do |repo|
99104
# sometimes language can be nil
@@ -126,6 +131,7 @@ check out ["D3 for Mortals"][D3 mortals].
126131
D3 is a JavaScript library, and likes working with data as arrays. So, let's convert our Ruby hash into
127132
a JSON array for use by JavaScript in the browser.
128133

134+
#!ruby
129135
languages = []
130136
language_obj.each do |lang, count|
131137
languages.push :language => lang, :count => count
@@ -141,6 +147,7 @@ Now, _lang_freq.erb_ is going to need some JavaScript to support rendering a bar
141147
For now, you can just use the code provided here, and refer to the resources linked above
142148
if you want to learn more about how D3 works:
143149

150+
#!html
144151
<!DOCTYPE html>
145152
<meta charset="utf-8">
146153
<html>
@@ -239,6 +246,7 @@ should be a great way to visualize the sizes of our coding languages used, rathe
239246
than simply the count. We'll need to construct an array of objects that looks
240247
something like this:
241248

249+
#!javascript
242250
[ { "name": "language1", "size": 100},
243251
{ "name": "language2", "size": 23}
244252
...
@@ -247,13 +255,15 @@ something like this:
247255
Since we already have a list of repositories above, let's inspect each one, and
248256
call [the language listing API method][language API]:
249257

258+
#!ruby
250259
repos.each do |repo|
251260
repo_name = repo.name
252261
repo_langs = octokit_client.languages("#{github_user.login}/#{repo_name}")
253262
end
254263

255264
From there, we'll cumulatively add each language found to a "master list":
256265

266+
#!ruby
257267
repo_langs.each do |lang, count|
258268
if !language_obj[lang]
259269
language_obj[lang] = count
@@ -264,6 +274,7 @@ From there, we'll cumulatively add each language found to a "master list":
264274

265275
After that, we'll format the contents into a structure that D3 understands:
266276

277+
#!ruby
267278
language_obj.each do |lang, count|
268279
language_byte_count.push :name => "#{lang} (#{count})", :count => count
269280
end
@@ -275,12 +286,14 @@ After that, we'll format the contents into a structure that D3 understands:
275286

276287
To wrap up, we pass this JSON information over to the same ERB template:
277288

289+
#!ruby
278290
erb :lang_freq, :locals => { :languages => languages.to_json, :language_byte_count => language_bytes.to_json}
279291

280292

281293
Like before, here's a bunch of JavaScript that you can drop
282294
directly into your template:
283295

296+
#!html
284297
<div id="byte_freq"></div>
285298
<script>
286299
var language_bytes = <%= language_byte_count %>

0 commit comments

Comments
 (0)