Skip to content

Commit 4c1c462

Browse files
piotrmurachpiotrmurach
committed
Start rewriting documentation.
1 parent b1da9b4 commit 4c1c462

1 file changed

Lines changed: 88 additions & 71 deletions

File tree

‎README.md‎

Lines changed: 88 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,13 @@ gem "github_api"
5151
## Contents
5252

5353
* [1. Usage](#1-usage)
54+
* [1.1 API Navigation](#11-api-navigation)
55+
* [1.2 Modularity](#12-modularity)
56+
* [1.3 Response Querying](#13-respone-querying)
57+
* [2. Configuration](#2-configuration)
58+
* [2.1 Basic](#21-configuration)
59+
* [2.2 Advanced](#22-configuration)
5460
* [2. Arguments & Parameters](#2-arguments--parameters)
55-
* [3. Advanced Configuration](#3-advanced-configuration)
5661
* [4. Authentication](#4-authentication)
5762
* [5. SSL](#5-ssl)
5863
* [6. API](#6-api)
@@ -69,96 +74,130 @@ gem "github_api"
6974

7075
## 1 Usage
7176

72-
To start using the gem, you can either perform direct calls on `Github`
77+
To start using the gem, you can either perform requests directly on `Github` namespace:
7378

7479
```ruby
75-
Github.repos.list user: 'wycats'
80+
Github.repos.list user: 'peter-murach'
7681
```
7782

78-
or create a new client instance
83+
or create a new client instance like so
7984

8085
```ruby
8186
github = Github.new
8287
```
8388

84-
### 1.1 Options
89+
and then call api methods, for instance, to list a given user repositories do
8590

86-
At this stage, you can also supply various configuration parameters, such as
91+
```ruby
92+
github.repos.list user: 'peter-murach'
8793
```
88-
adapter # http client used for performing requests
89-
auto_pagination # false by default, set to true to traverse requests page links
90-
oauth_token # oauth authorization token
91-
basic_auth # login:password string
92-
client_id # oauth client id
93-
client_secret # oauth client secret
94-
user # global user used in requests if none provided
95-
repo # global repository used in requests in none provided
96-
org # global organization used in requests if none provided
97-
endpoint # enterprise API endpoint
98-
site # enterprise API web endpoint
99-
ssl # SSL settings
100-
per_page # number of items per page- max of 100
101-
user_agent # custom user agent name, 'Github API' by default
94+
95+
### 1.1 API Navigation
96+
97+
This gem closely mirrors the GitHub API hierarchy i.e. if you want to create a download resource, look up the GitHub API spec and issue the request as in `github.repos.downloads.create`
98+
99+
For example to interact with GitHub Repositories API, issue the following calls that correspond directly to the GitHub API hierarchy
100+
101+
```ruby
102+
github.repos.commits.all 'user-name', 'repo-name'
103+
github.repos.hooks.create 'user-name', 'repo-name', name: "web", active: true
104+
github.repos.keys.get 'user-name', 'repo-name'
102105
```
103-
which are used throughout the API. These can be passed directly as hash options:
106+
107+
### 1.2 Modularity
108+
109+
The code base is modular and allows for you to work specifically with a given part of GitHub API e.g. blobs
104110

105111
```ruby
106-
github = Github.new oauth_token: 'token'
112+
blobs = Github::Client::GitData::Blobs.new
113+
blobs.create 'peter-murach', 'github', content: 'Blob content'
107114
```
108115

109-
Alternatively, you can configure the GitHub settings by passing a block, for instance, for a custom enterprise endpoint and website like
116+
### 1.3 Response Querying
117+
The response is of type [Github::ResponseWrapper] which allows traversing all the json response attributes like method calls i.e.
110118

111119
```ruby
112-
github = Github.new do |config|
113-
config.endpoint = 'https://github.company.com/api/v3'
114-
config.site = 'https://github.company.com'
115-
config.oauth_token = 'token'
116-
config.adapter = :net_http
117-
config.ssl = {:verify => false}
120+
repos = Github::Client::Repos.new user: 'peter-murach', repo: 'github'
121+
repos.branches do |branch|
122+
puts branch.name
118123
end
119124
```
120125

121-
You can authenticate either using OAuth authentication convenience methods (see OAuth section) or through basic authentication by passing your login and password credentials
126+
## 2 Configuration
127+
128+
The **github_api** provides ability to specify global configruation options. These options will be available to all api calls.
129+
130+
### 2.1 Basic
131+
132+
The configuration options can be set by using the `configure` helper
122133

123134
```ruby
124-
github = Github.new login:'peter-murach', password:'...'
135+
Github.configure do |c|
136+
c.basic_auth = "login:password"
137+
c.adapter = :typheous
138+
c.user = 'peter-murach'
139+
c.repo = 'finite_machine'
140+
end
125141
```
126142

127-
or using a convenience method:
143+
Alternatively, you can configure the settings by passing a block to an instance like:
128144

129145
```ruby
130-
github = Github.new basic_auth: 'login:password'
146+
Github.new do |c|
147+
c.endpoint = 'https://github.company.com/api/v3'
148+
c.site = 'https://github.company.com'
149+
end
131150
```
132151

133-
### 1.2 API navigation
152+
or simply by passing hash of options to an instance like so
134153

135-
This gem closely mirrors the GitHub API hierarchy i.e. if you want to create a download resource,
136-
look up the GitHub API spec and issue the request as in `github.repos.downloads.create`
154+
```ruby
155+
github = Github.new basic_auth: 'login:password',
156+
adapter: :typheous,
157+
user: 'peter-murach',
158+
repo: 'finite_machine'
159+
```
137160

138-
For example to interact with GitHub Repositories API, issue the following calls that correspond directly to the GitHub API hierarchy
161+
The following is the full list of available configuration options:
139162

140163
```ruby
141-
github.repos.commits.all 'user-name', 'repo-name'
142-
github.repos.hooks.create 'user-name', 'repo-name', name: "web", active: true
143-
github.repos.keys.get 'user-name', 'repo-name'
164+
adapter # Http client used for performing requests. Default :net_http
165+
auto_pagination # Automatically traverse requests page links. Default false
166+
basic_auth # Basic authentication in form login:password.
167+
client_id # Oauth client id.
168+
client_secret # Oauth client secret.
169+
connection_options # Hash of connection options.
170+
endpoint # Enterprise API endpoint. Default: 'https://api.github.com'
171+
oauth_token # Oauth authorization token.
172+
org # Global organization used in requests if none provided
173+
per_page # Number of items per page. Max of 100. Default 30.
174+
repo # Global repository used in requests in none provided
175+
site # enterprise API web endpoint
176+
ssl # SSL settings in hash form.
177+
user # Global user used for requests if none provided
178+
user_agent # Custom user agent name. Default 'Github API Ruby Gem'
144179
```
145180

146-
### 1.3 Modularity
181+
### 2.2 Advanced
147182

148-
The code base is modular and allows for you to work specifically with a given part of GitHub API e.g. blobs
183+
The **github_api** will use the default middleware stack which is exposed by calling `stack` on a client instance. However, this stack can be freely modified with methods such as `insert`, `insert_after`, `delete` and `swap`. For instance, to add your `CustomMiddleware` do:
149184

150185
```ruby
151-
blobs = Github::GitData::Blobs.new
152-
blobs.create 'peter-murach', 'github', content: 'Blob content'
186+
Github.configure do |c|
187+
c.stack.insert_after Github::Response::Helpers, CustomMiddleware
188+
end
153189
```
154190

155-
### 1.4 Response querying
156-
The response is of type [Github::ResponseWrapper] which allows traversing all the json response attributes like method calls i.e.
191+
Furthermore, you can build your entire custom stack and specify other connection options such as `adapter` by doing:
157192

158193
```ruby
159-
repos = Github::Repos.new user: 'peter-murach', repo: 'github'
160-
repos.branches do |branch|
161-
puts branch.name
194+
Github.new do |c|
195+
c.adapter :excon
196+
197+
c.stack do |builder|
198+
builder.use Github::Response::Helpers
199+
builder.use Github::Response::Jsonize
200+
end
162201
end
163202
```
164203

@@ -229,28 +268,6 @@ github.git_data.trees.get 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031
229268
end
230269
```
231270

232-
## 3 Advanced Configuration
233-
234-
The `github_api` gem will use the default middleware stack which is exposed by calling `stack` on a client instance. However, this stack can be freely modified with methods such as `insert`, `insert_after`, `delete` and `swap`. For instance, to add your `CustomMiddleware` do
235-
236-
```ruby
237-
github = Github.new do |config|
238-
config.stack.insert_after Github::Response::Helpers, CustomMiddleware
239-
end
240-
```
241-
242-
Furthermore, you can build your entire custom stack and specify other connection options such as `adapter`
243-
244-
```ruby
245-
github = Github.new do |config|
246-
config.adapter :excon
247-
248-
config.stack do |builder|
249-
builder.use Github::Response::Helpers
250-
builder.use Github::Response::Jsonize
251-
end
252-
end
253-
```
254271

255272
## 4 Authentication
256273

0 commit comments

Comments
 (0)