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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
# Configuration
Twitter API version 1.1 requires authentication on all requests. Some requests
can be made with [application-only authentication][application-only] while
other requests require [single-user authentication][single-user].
[application-only]: https://dev.twitter.com/oauth/application-only
[single-user]: https://dev.twitter.com/oauth/overview/single-user
## Application-only Authentication
To start using the Twitter API, you need to [register your application with
Twitter][register]. Registration requires you to answer some questions about
your application and agree to the [Twitter API Terms of Use][api-terms].
[register]: https://apps.twitter.com/
[api-terms]: https://dev.twitter.com/overview/terms/agreement-and-policy
Once you've registered an application, it's important that you set the correct
access level. Otherwise you may see the error:
Read-only application cannot POST
Your new application will be assigned a consumer key/secret pair that
identifies your application to Twitter. This is all you need to configure your
client for application-only authentication.
```ruby
client = Twitter::REST::Client.new do |config|
config.consumer_key = "YOUR_CONSUMER_KEY"
config.consumer_secret = "YOUR_CONSUMER_SECRET"
end
```
If you prefer, you can pass in configuration as a `Hash`:
```ruby
config = {
consumer_key: "YOUR_CONSUMER_KEY",
consumer_secret: "YOUR_CONSUMER_SECRET",
}
client = Twitter::REST::Client.new(config)
```
Regardless of your configuration style, you should now be able to use this
client to make any Twitter API request that does not require single-user
authentication. For example:
```ruby
client.user("sferik")
```
Note: The first time this method is called, it will make two API requests.
First, it will fetch an access token to perform the request. Then, it will
fetch the requested user. The access token will be cached for subsequent
requests made with the same client but you may wish to manually fetch the
access token once and use it when initializing clients to avoid making two
requests every time.
```ruby
client.bearer_token
```
This token never expires and will not change unless it is invalidated. Once
you've obtained a bearer token, you can use it to initialize clients to avoid
making an extra request.
```ruby
client = Twitter::REST::Client.new do |config|
config.consumer_key = "YOUR_CONSUMER_KEY"
config.consumer_secret = "YOUR_CONSUMER_SECRET"
config.bearer_token = "YOUR_BEARER_TOKEN"
end
```
## Single-user Authentication
Not all Twitter API resources are accessible with application-only
authentication. Some resources require single-user authentication tokens, which
you can obtain from the [3-legged authorization][3-legged-authorization] flow.
[3-legged-authorization]: https://dev.twitter.com/oauth/3-legged
```ruby
client = Twitter::REST::Client.new do |config|
config.consumer_key = "YOUR_CONSUMER_KEY"
config.consumer_secret = "YOUR_CONSUMER_SECRET"
config.access_token = "YOUR_ACCESS_TOKEN"
config.access_token_secret = "YOUR_ACCESS_SECRET"
end
```
You can use this client to make any Twitter REST API request. For example:
```ruby
client.update("I'm tweeting with @gem!")
```
## Premium Search API
```ruby
client = Twitter::REST::Client.new do |config|
config.consumer_key = "YOUR_CONSUMER_KEY"
config.consumer_secret = "YOUR_CONSUMER_SECRET"
config.dev_environment = "YOUR_DEV_ENVIRONMENT"
end
```
You can use this client to make a REST 30-Day or Fullarchive Search API request. For example:
```ruby
client.premium_search("#ruby", { maxResults: 100 }, { product: 'fullarchive' })
```
## Streaming Clients
Streaming clients are initialized just like single-user authenticated REST
clients:
```ruby
client = Twitter::Streaming::Client.new do |config|
config.consumer_key = "YOUR_CONSUMER_KEY"
config.consumer_secret = "YOUR_CONSUMER_SECRET"
config.access_token = "YOUR_ACCESS_TOKEN"
config.access_token_secret = "YOUR_ACCESS_SECRET"
end
```
```ruby
client.sample do |object|
puts object.text if object.is_a?(Twitter::Tweet)
end
```
For more information, see the documentation for the
[`Twitter::Client`][client], [`Twitter::REST::Client`][rest-client], and
[`Twitter::Streaming::Client`][streaming-client] classes.
[client]: http://rdoc.info/gems/twitter/Twitter/Client
[rest-client]: http://rdoc.info/gems/twitter/Twitter/REST/Client
[streaming-client]: http://rdoc.info/gems/twitter/Twitter/Streaming/Client
## Using a Proxy
If you'd like to connect via a proxy, a proxy can be configured by passing a
`Hash` to your configuration:
```ruby
proxy = {
host: "proxy.example.com",
port: 8080,
username: "proxy_username",
password: "proxy_password"
}
client = Twitter::REST::Client.new do |config|
config.consumer_key = "YOUR_CONSUMER_KEY"
config.consumer_secret = "YOUR_CONSUMER_SECRET"
config.access_token = "YOUR_ACCESS_TOKEN"
config.access_token_secret = "YOUR_ACCESS_SECRET"
config.proxy = proxy
end
```
Note that only a `host` and `port` are required, but a `username` and `password`
can be optionally configured for an authenticated proxy server. Proxies are
supported by both [`Twitter::REST::Client`][rest-client] and
[`Twitter::Streaming::Client`][streaming-client] classes.
|
