Skip to content

Commit b00bfb8

Browse files
pengwynnpengwynn
committed
Clarify rest-client
1 parent 86e0352 commit b00bfb8

File tree

6 files changed

+100
-92
lines changed

6 files changed

+100
-92
lines changed

‎changes.atom‎

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<feed xmlns="http://www.w3.org/2005/Atom">
33
<id>http://developer.github.com/</id>
44
<title>GitHub API Changes</title>
5-
<updated>2013-03-01T08:00:00Z</updated>
5+
<updated>2013-03-01T06:00:00Z</updated>
66
<link rel="alternate" href="http://developer.github.com/" />
77
<link rel="self" href="http://developer.github.com/changes.atom" />
88
<author>
@@ -12,8 +12,8 @@
1212
<entry>
1313
<id>tag:developer.github.com,2013-03-01:/changes/2013-3-1-new-hookshot-coming/</id>
1414
<title type="html">New Hookshot Changes</title>
15-
<published>2013-03-01T08:00:00Z</published>
16-
<updated>2013-03-01T08:00:00Z</updated>
15+
<published>2013-03-01T06:00:00Z</published>
16+
<updated>2013-03-01T06:00:00Z</updated>
1717
<author>
1818
<name>technoweenie</name>
1919
<uri>https://github.com/technoweenie</uri>
@@ -40,8 +40,8 @@ requests&lt;/a&gt; very soon :)&lt;/p&gt;</content>
4040
<entry>
4141
<id>tag:developer.github.com,2013-02-14:/changes/2013-2-13-sortable-stars/</id>
4242
<title type="html">Sortable Stars in Repository Starring API</title>
43-
<published>2013-02-14T08:00:00Z</published>
44-
<updated>2013-02-14T08:00:00Z</updated>
43+
<published>2013-02-14T06:00:00Z</published>
44+
<updated>2013-02-14T06:00:00Z</updated>
4545
<author>
4646
<name>pengwynn</name>
4747
<uri>https://github.com/technoweenie</uri>
@@ -100,8 +100,8 @@ if you have any questions.&lt;/p&gt;</content>
100100
<entry>
101101
<id>tag:developer.github.com,2013-02-05:/changes/2013-2-5-changes-to-services/</id>
102102
<title type="html">Upcoming Changes to GitHub Services</title>
103-
<published>2013-02-05T08:00:00Z</published>
104-
<updated>2013-02-05T08:00:00Z</updated>
103+
<published>2013-02-05T06:00:00Z</published>
104+
<updated>2013-02-05T06:00:00Z</updated>
105105
<author>
106106
<name>technoweenie</name>
107107
<uri>https://github.com/technoweenie</uri>
@@ -139,8 +139,8 @@ over 100 services is taking too much of this focus away.&lt;/p&gt;</content>
139139
<entry>
140140
<id>tag:developer.github.com,2013-01-31:/changes/2013-01-31-user-agent-will-soon-be-mandatory/</id>
141141
<title type="html">User Agent mandatory from March 4th 2013</title>
142-
<published>2013-01-31T08:00:00Z</published>
143-
<updated>2013-01-31T08:00:00Z</updated>
142+
<published>2013-01-31T06:00:00Z</published>
143+
<updated>2013-01-31T06:00:00Z</updated>
144144
<author>
145145
<name>agh</name>
146146
<uri>https://github.com/technoweenie</uri>
@@ -164,8 +164,8 @@ many of our users to make any changes whatsoever.&lt;/p&gt;
164164
<entry>
165165
<id>tag:developer.github.com,2013-01-08:/changes/2013-01-08-new-user-scopes/</id>
166166
<title type="html">New User scopes</title>
167-
<published>2013-01-08T08:00:00Z</published>
168-
<updated>2013-01-08T08:00:00Z</updated>
167+
<published>2013-01-08T06:00:00Z</published>
168+
<updated>2013-01-08T06:00:00Z</updated>
169169
<author>
170170
<name>technoweenie</name>
171171
<uri>https://github.com/technoweenie</uri>
@@ -187,8 +187,8 @@ can be potentially dangerous.&lt;/p&gt;
187187
<entry>
188188
<id>tag:developer.github.com,2012-12-10:/changes/2012-12-10-Diff-and-patch-media-types/</id>
189189
<title type="html">Diff and patch media types</title>
190-
<published>2012-12-10T08:00:00Z</published>
191-
<updated>2012-12-10T08:00:00Z</updated>
190+
<published>2012-12-10T06:00:00Z</published>
191+
<updated>2012-12-10T06:00:00Z</updated>
192192
<author>
193193
<name>pengwynn</name>
194194
<uri>https://github.com/technoweenie</uri>
@@ -221,8 +221,8 @@ index 1f599cb..abaf625 100755
221221
<entry>
222222
<id>tag:developer.github.com,2012-12-09:/changes/2012-12-09-organization-repositories-results-now-paginate/</id>
223223
<title type="html">Pagination for Organization Repository lists now paginates properly</title>
224-
<published>2012-12-09T08:00:00Z</published>
225-
<updated>2012-12-09T08:00:00Z</updated>
224+
<published>2012-12-09T06:00:00Z</published>
225+
<updated>2012-12-09T06:00:00Z</updated>
226226
<author>
227227
<name>rick</name>
228228
<uri>https://github.com/technoweenie</uri>
@@ -244,8 +244,8 @@ regardless of what you send in the &lt;code&gt;type&lt;/code&gt; parameter.&lt;/
244244
<entry>
245245
<id>tag:developer.github.com,2012-12-08:/changes/2012-12-08-finding-source-and-fork-repos-for-organizations/</id>
246246
<title type="html">Finding sources and fork repositories for organizations</title>
247-
<published>2012-12-08T08:00:00Z</published>
248-
<updated>2012-12-08T08:00:00Z</updated>
247+
<published>2012-12-08T06:00:00Z</published>
248+
<updated>2012-12-08T06:00:00Z</updated>
249249
<author>
250250
<name>rick</name>
251251
<uri>https://github.com/technoweenie</uri>
@@ -273,8 +273,8 @@ curl "https://api.github.com/orgs/:org/repos?type=sources"
273273
<entry>
274274
<id>tag:developer.github.com,2012-12-06:/changes/2012-12-06-create-authorization-for-app/</id>
275275
<title type="html">Create an OAuth authorization for an app</title>
276-
<published>2012-12-06T08:00:00Z</published>
277-
<updated>2012-12-06T08:00:00Z</updated>
276+
<published>2012-12-06T06:00:00Z</published>
277+
<updated>2012-12-06T06:00:00Z</updated>
278278
<author>
279279
<name>pengwynn</name>
280280
<uri>https://github.com/technoweenie</uri>
@@ -311,8 +311,8 @@ app’s rate limit.&lt;/p&gt;</content>
311311
<entry>
312312
<id>tag:developer.github.com,2012-12-04:/changes/2012-12-04-List-comments-for-repo/</id>
313313
<title type="html">Per-repository Review and Issue Comment&amp;nbsp;listing</title>
314-
<published>2012-12-04T08:00:00Z</published>
315-
<updated>2012-12-04T08:00:00Z</updated>
314+
<published>2012-12-04T06:00:00Z</published>
315+
<updated>2012-12-04T06:00:00Z</updated>
316316
<author>
317317
<name>pengwynn</name>
318318
<uri>https://github.com/technoweenie</uri>
@@ -342,8 +342,8 @@ curl https://api.github.com/repos/mathiasbynens/dotfiles/pulls/comments
342342
<entry>
343343
<id>tag:developer.github.com,2012-11-29:/changes/2012-11-29-gitignore-templates/</id>
344344
<title type="html">Gitignore Templates API</title>
345-
<published>2012-11-29T08:00:00Z</published>
346-
<updated>2012-11-29T08:00:00Z</updated>
345+
<published>2012-11-29T06:00:00Z</published>
346+
<updated>2012-11-29T06:00:00Z</updated>
347347
<author>
348348
<name>pengwynn</name>
349349
<uri>https://github.com/technoweenie</uri>
@@ -401,8 +401,8 @@ DerivedData
401401
<entry>
402402
<id>tag:developer.github.com,2012-11-27:/changes/2012-11-27-forking-to-organizations/</id>
403403
<title type="html">Forking to Organizations</title>
404-
<published>2012-11-27T08:00:00Z</published>
405-
<updated>2012-11-27T08:00:00Z</updated>
404+
<published>2012-11-27T06:00:00Z</published>
405+
<updated>2012-11-27T06:00:00Z</updated>
406406
<author>
407407
<name>technoweenie</name>
408408
<uri>https://github.com/technoweenie</uri>
@@ -436,8 +436,8 @@ major change of the GitHub API.&lt;/p&gt;</content>
436436
<entry>
437437
<id>tag:developer.github.com,2012-10-31:/changes/2012-10-31-gist-comment-uris/</id>
438438
<title type="html">Gist comment URIs</title>
439-
<published>2012-10-31T07:00:00Z</published>
440-
<updated>2012-10-31T07:00:00Z</updated>
439+
<published>2012-10-31T05:00:00Z</published>
440+
<updated>2012-10-31T05:00:00Z</updated>
441441
<author>
442442
<name>pezra</name>
443443
<uri>https://github.com/technoweenie</uri>
@@ -452,8 +452,8 @@ major change of the GitHub API.&lt;/p&gt;</content>
452452
<entry>
453453
<id>tag:developer.github.com,2012-10-26:/changes/2012-10-26-notifications-api/</id>
454454
<title type="html">Notifications API</title>
455-
<published>2012-10-26T07:00:00Z</published>
456-
<updated>2012-10-26T07:00:00Z</updated>
455+
<published>2012-10-26T05:00:00Z</published>
456+
<updated>2012-10-26T05:00:00Z</updated>
457457
<author>
458458
<name>technoweenie</name>
459459
<uri>https://github.com/technoweenie</uri>
@@ -523,8 +523,8 @@ X-Poll-Interval: 60
523523
<entry>
524524
<id>tag:developer.github.com,2012-10-24:/changes/2012-10-24-set-default-branch/</id>
525525
<title type="html">Set the default branch for a repository</title>
526-
<published>2012-10-24T07:00:00Z</published>
527-
<updated>2012-10-24T07:00:00Z</updated>
526+
<published>2012-10-24T05:00:00Z</published>
527+
<updated>2012-10-24T05:00:00Z</updated>
528528
<author>
529529
<name>pengwynn</name>
530530
<uri>https://github.com/technoweenie</uri>
@@ -547,8 +547,8 @@ curl -u pengwynn \
547547
<entry>
548548
<id>tag:developer.github.com,2012-10-17:/changes/2012-10-17-org-members-redirection/</id>
549549
<title type="html">Organization Members Resource Changes</title>
550-
<published>2012-10-17T07:00:00Z</published>
551-
<updated>2012-10-17T07:00:00Z</updated>
550+
<published>2012-10-17T05:00:00Z</published>
551+
<updated>2012-10-17T05:00:00Z</updated>
552552
<author>
553553
<name>pezra</name>
554554
<uri>https://github.com/technoweenie</uri>
@@ -577,8 +577,8 @@ should be using the public membership resources.&lt;/p&gt;
577577
<entry>
578578
<id>tag:developer.github.com,2012-10-14:/changes/2012-10-14-rate-limit-changes/</id>
579579
<title type="html">Rate limit changes for unauthenticated requests</title>
580-
<published>2012-10-14T07:00:00Z</published>
581-
<updated>2012-10-14T07:00:00Z</updated>
580+
<published>2012-10-14T05:00:00Z</published>
581+
<updated>2012-10-14T05:00:00Z</updated>
582582
<author>
583583
<name>pengwynn</name>
584584
<uri>https://github.com/technoweenie</uri>
@@ -605,8 +605,8 @@ something unique to your application.&lt;/p&gt;
605605
<entry>
606606
<id>tag:developer.github.com,2012-09-28:/changes/2012-9-28-auto-init-for-repositories/</id>
607607
<title type="html">Initialize a repository when creating</title>
608-
<published>2012-09-28T07:00:00Z</published>
609-
<updated>2012-09-28T07:00:00Z</updated>
608+
<published>2012-09-28T05:00:00Z</published>
609+
<updated>2012-09-28T05:00:00Z</updated>
610610
<author>
611611
<name>pengwynn</name>
612612
<uri>https://github.com/technoweenie</uri>
@@ -653,8 +653,8 @@ is ignored if &lt;code&gt;auto_init&lt;/code&gt; is not present and &lt;code&gt;
653653
<entry>
654654
<id>tag:developer.github.com,2012-09-05:/changes/2012-9-5-watcher-api/</id>
655655
<title type="html">Upcoming Changes to Watcher and Star APIs</title>
656-
<published>2012-09-05T07:00:00Z</published>
657-
<updated>2012-09-05T07:00:00Z</updated>
656+
<published>2012-09-05T05:00:00Z</published>
657+
<updated>2012-09-05T05:00:00Z</updated>
658658
<author>
659659
<name>technoweenie</name>
660660
<uri>https://github.com/technoweenie</uri>

‎guides/basics-of-authentication/index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ <h2 id="accepting-user-authorization">Accepting user authorization</h2>
7171
<p>Now, let’s start filling out our simple server. Create a file called <em>server.rb</em> and paste this into it:</p>
7272

7373
<pre><code>require 'sinatra'
74-
require 'rest_client'
74+
require 'rest-client'
7575

7676
CLIENT_ID = ENV['GH_BASIC_CLIENT_ID']
7777
CLIENT_SECRET = ENV['GH_BASIC_SECRET_ID']
@@ -173,7 +173,7 @@ <h2 id="implementing-persistent-authentication">Implementing “persistent” au
173173
and paste these lines into it:</p>
174174

175175
<pre><code>require 'sinatra/auth/github'
176-
require 'rest_client'
176+
require 'rest-client'
177177

178178
module Example
179179
class MyBasicApp &lt; Sinatra::Base

‎guides/getting-started/index.html‎

Lines changed: 36 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ <h3 id="hello-world">Hello World</h3>
9696
Last-Modified: Tue, 30 Oct 2012 18:58:42 GMT
9797
</code></pre>
9898

99-
<p>There’s a few interesting bits in the response headers. As expected, the
99+
<p>There are a few interesting bits in the response headers. As expected, the
100100
<code>Content-Type</code> is <code>application/json</code>. </p>
101101

102102
<p>Any headers beginning with <code>X-</code> are custom headers, and are not included in the
@@ -108,12 +108,12 @@ <h3 id="hello-world">Hello World</h3>
108108
talk more about that later.</li>
109109
<li>Take note of the <code>X-RateLimit-Limit</code> and <code>X-RateLimit-Remaining</code> headers. This
110110
pair of headers indicate how many requests a client can make in a rolling hour
111-
and how many of those requests it has already spent.</li>
111+
and how many of those requests the client has already spent.</li>
112112
</ul>
113113

114114
<h2 id="authentication">Authentication</h2>
115115

116-
<p>Unauthenticated clients can make 60 calls per hour. To get more, we’ll need to
116+
<p>Unauthenticated clients can make 60 requests per hour. To get more, we’ll need to
117117
<em>authenticate</em>. In fact, doing anything interesting with the GitHub API requires
118118
authentication.</p>
119119

@@ -129,21 +129,25 @@ <h3 id="basic">Basic</h3>
129129
<p>The <code>-u</code> flag sets the username, and cURL will prompt you for the password. You
130130
can use <code>-u "username:password"</code> to avoid the prompt, but this leaves your
131131
password in shell history and isn’t recommended. When authenticating, you
132-
should see your rate limit bumped to 5000 requests an hour, as indicated in the
132+
should see your rate limit bumped to 5,000 requests an hour, as indicated in the
133133
<code>X-RateLimit-Limit</code> header.</p>
134134

135135
<p>In addition to just getting more calls per hour, authentication is the key to
136136
reading and writing private information via the API.</p>
137137

138138
<h3 id="get-your-own-user-profile">Get your own user profile</h3>
139139

140-
<p>When properly authenticated, you can grab your own user profile:</p>
140+
<p>When properly authenticated, you can take advantage of the permissions
141+
associated with your GitHub account. For example, try getting your own
142+
user profile:</p>
141143

142144
<pre><code>curl -i -u &lt;your_username&gt; https://api.github.com/user
143145
</code></pre>
144146

145-
<p>This time, in addition to the same set of information we retrieved for defunkt
146-
earlier, you should see a <code>plan</code> object on the response:</p>
147+
<p>This time, in addition to the same set of public information we
148+
retrieved for defunkt earlier, you should also see the non-public
149+
information for your user profile. For example, you see a <code>plan</code> object
150+
on the response:</p>
147151

148152
<pre><code>...
149153
"plan": {
@@ -157,7 +161,7 @@ <h3 id="get-your-own-user-profile">Get your own user profile</h3>
157161

158162
<h3 id="oauth">OAuth</h3>
159163

160-
<p>While convenient, Basic Auth isn’t ideal because you shouldn’t give your GitHub
164+
<p>While convenient, Basic Authentication isn’t ideal because you shouldn’t give your GitHub
161165
username and password to anyone. Applications that need to read or write
162166
private information using the API on behalf of another user should use <a href="http://developer.github.com/v3/oauth/">OAuth</a>.</p>
163167

@@ -166,25 +170,29 @@ <h3 id="oauth">OAuth</h3>
166170

167171
<ul>
168172
<li><strong>Revokable access</strong>: users can revoke authorization to third party apps at any time</li>
169-
<li><strong>Limited access</strong>: users can specify what access a token provides when they
170-
authorize a third party app</li>
173+
<li><strong>Limited access</strong>: users can review the specific access that a token
174+
will provide before authorizing a third party app</li>
171175
</ul>
172176

173-
<p>Normally, tokens are created via a <a href="http://developer.github.com/v3/oauth/#web-application-flow">web flow</a>. An application will send
174-
users to GitHub to log in. GitHub will present a dialog indicating the name of the
175-
app, as well as what information it has access to. After a user authorizes access,
176-
GitHub redirects the user back to the application:<br />
177+
<p>Normally, tokens are created via a <a href="http://developer.github.com/v3/oauth/#web-application-flow">web flow</a>. An application
178+
sends users to GitHub to log in. GitHub then presents a dialog
179+
indicating the name of the app, as well as the level of access the app
180+
has once it’s authorized by the user. After a user authorizes access, GitHub
181+
redirects the user back to the application:
177182
<img src="/images/oauth_prompt.png" alt="" /></p>
178183

179184
<p>You don’t need to set up the entire web flow to begin working with OAuth tokens.
180-
The <a href="http://developer.github.com/v3/oauth/#oauth-authorizations-api">Authorizations API</a> makes it simple to use Basic Auth
181-
to create an OAuth token. Try pasting and running </p>
185+
The <a href="http://developer.github.com/v3/oauth/#oauth-authorizations-api">Authorizations API</a> makes it simple to use Basic Authentication
186+
to create an OAuth token. Try pasting and running the following command:</p>
182187

183188
<pre><code>curl -i -u &lt;your_username&gt; \
184189
-d '{"scopes": ["repo"]}' \
185190
https://api.github.com/authorizations
191+
</code></pre>
192+
193+
<p>You should see output similar to this:</p>
186194

187-
HTTP/1.1 201 Created
195+
<pre><code>HTTP/1.1 201 Created
188196
Server: nginx/1.0.14
189197
Date: Wed, 14 Nov 2012 14:04:24 GMT
190198
Content-Type: application/json; charset=utf-8
@@ -273,8 +281,10 @@ <h2 id="repositories">Repositories</h2>
273281
<p>The information returned from these calls will depend on how we authenticate:</p>
274282

275283
<ul>
276-
<li>Using Basic Auth, everything the user has access to see on github.com</li>
277-
<li>Using OAuth, private repositories are only returned if the OAuth token contains ‘repo’ scope.</li>
284+
<li>Using Basic Authentication, the response includes all repositories the
285+
the user has access to see on github.com.</li>
286+
<li>Using OAuth, private repositories are only returned if the OAuth token
287+
contains the <code>repo</code> <a href="http://developer.github.com/v3/oauth/#scopes">scope</a>.</li>
278288
</ul>
279289

280290
<p>As the <a href="http://developer.github.com/v3/repos/">docs</a> indicate, these methods take a <code>type</code> parameter that
@@ -285,7 +295,7 @@ <h2 id="repositories">Repositories</h2>
285295
<pre><code>curl -i "https://api.github.com/users/technoweenie/repos?type=owner"
286296
</code></pre>
287297

288-
<p>In this example, we can grab only those repositories that technoweenie owns, not the
298+
<p>In this example, we grab only those repositories that technoweenie owns, not the
289299
ones on which he collaborates. Note the quoted URL above. Depending on your
290300
shell setup, cURL sometimes requires a quoted URL or else it ignores the
291301
querystring.</p>
@@ -313,8 +323,8 @@ <h3 id="create-a-repository">Create a repository</h3>
313323

314324
<p>The resulting repository will be found at <code>https://github.com/&lt;your
315325
username&gt;/blog</code>. To create a repository under an organization for which you’re
316-
an owner, just change the API method from <code>/user/repos</code> to <code>/orgs/{org
317-
name}/repos</code>.</p>
326+
an owner, just change the API method from <code>/user/repos</code> to <code>/orgs/&lt;org
327+
name&gt;/repos</code>.</p>
318328

319329
<p>Next, let’s fetch our newly created repository:</p>
320330

@@ -330,7 +340,7 @@ <h3 id="create-a-repository">Create a repository</h3>
330340
<p>Oh noes! Where did it go? Since we created the repository as <em>private</em>, we need
331341
to authenticate in order to see it. If you’re a grizzled HTTP user, you might
332342
expect a <code>403</code> instead. Since we don’t want to leak information about private
333-
repositories, the GitHub API returns a <code>404</code> instead, as if to say “we can
343+
repositories, the GitHub API returns a <code>404</code> in this case, as if to say “we can
334344
neither confirm nor deny the existence of this repository.”</p>
335345

336346
<h2 id="issues">Issues</h2>
@@ -348,7 +358,7 @@ <h2 id="issues">Issues</h2>
348358
</code></pre>
349359

350360
<p>To get only the issues under one of your GitHub organizations, call <code>GET
351-
/orgs/{org}/issues</code>:</p>
361+
/orgs/&lt;org&gt;/issues</code>:</p>
352362

353363
<pre><code>curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
354364
https://api.github.com/orgs/rails/issues
@@ -461,8 +471,8 @@ <h3 id="convert-an-issue-to-a-pull-request">Convert an issue to a Pull Request</
461471

462472
<h2 id="conditional-requests">Conditional requests</h2>
463473

464-
<p>A big part of being a good API citizen is respecting rate limits and caching
465-
information that does not change. The API supports <a href="http://developer.github.com/v3/#conditional-requests">conditional
474+
<p>A big part of being a good API citizen is respecting rate limits by
475+
caching information that hasn’t changed. The API supports <a href="http://developer.github.com/v3/#conditional-requests">conditional
466476
requests</a> and helps you do the right thing. Consider the
467477
first call we made to get defunkt’s profile:</p>
468478

0 commit comments

Comments
 (0)