1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
# GH - Layered GitHub API client
[](https://travis-ci.com/travis-ci/gh)
This is a highly flexible, layered, low-level GitHub client library, trying to get out of your way and let you get to the GitHub data as simple as possible. Unless you add layers, you will end up with Hashes and Arrays. The approach and API should be familiar from projects like Rack or Faraday.
Simple example:
``` ruby
require 'gh'
puts GH['users/rkh']['name']
```
This will by default use all the middleware that ships with GH, in the following order:
* `GH::Remote` - sends HTTP requests to GitHub and parses the response
* `GH::Normalizer` - renames fields consistenly, adds hypermedia links if possible
* `GH::LazyLoader` - will load missing fields when accessed (handy for dealing with incomplete data without sending to many requests)
* `GH::MergeCommit` - adds infos about merge commits to pull request payloads
* `GH::LinkFollower` - will add content of hypermedia links as fields (lazyly), allows you to traverse relations
* `GH::Pagination` - adds support for transparent pagination
* `GH::Instrumentation` - let's you instrument `gh`
The following middleware is not included by default:
* `GH::Cache` - caches the responses (will use Rails cache if in Rails, in-memory cache otherwise)
## Main Entry Points
Every layer has two main entry points:
* `[key]` - loads data from GitHub
* `load(data)` - takes data and applies modifications (handy for dealing with service hook payloads)
These two methods are exposed by any instance of a layer and the `GH` constant.
## Using a Single Layer
You can initialize and use any layer on its own:
``` ruby
gh = GH::Remote.new
puts gh['users/rkh']['name']
```
Layers know which other layer they should usually wrap (`Remote` wraps no other layer, `LazyLoader` and `LinkFollower` wrap `Normalizer` by default, anything else wraps `Remote`), so you can initialize them right away:
``` ruby
gh = GH::LazyLoader.new
```
You can also pass the layer that should be wrapped as an argument:
``` ruby
gh = GH::LazyLoader.new(GH::LinkFollower.new)
```
## Creating Your Own Stack
For convinience a stack DSL is provided:
``` ruby
# Same as GH::Normalizer.new(GH::Cache.new)
gh = GH::Stack.build do
use GH::Normalizer
use GH::Cache
end
puts gh['users/rkh']['name']
```
You can also create reusable `Stack` instances:
``` ruby
stack = GH::Stack.new do
use GH::Normalizer
use GH::Cache
end
gh = stack.build username: 'rkh', password: 'abc123'
puts gh['user']['name']
```
One such instance (with the standard setup) can be accessed as `GH::DefaultStack`
## Scoping
With the main goal to separate authentication from other logic, the `gh` library supports scoping:
``` ruby
GH.with GH::LazyLoader.new do
puts GH['users/rkh']['name']
end
```
That way, you could create a stack with, for instance, an [access token](http://developer.github.com/v3/oauth/):
``` ruby
authenticated = GH::DefaultStack.build token: 'e72e16c7e42f292c6912e7710c838347ae178b4a'
GH.with(authenticated) do
# ...
end
```
Since this is rather common, you can pass options directly to `with`:
``` ruby
GH.with(username: 'rkh', password: 'abc123') do
# ...
end
```
Scoping is thread-safe.
## Is this production ready?
I hope so, we use it in production for [Travis CI](http://travis-ci.org/). The work on this library has been funded by the [Travis Love Campaign](https://love.travis-ci.org/).
|
