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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# httparty
Makes http fun again!
## Table of contents
- [Parsing JSON](#parsing-json)
- [Working with SSL](#working-with-ssl)
## Parsing JSON
If the response Content Type is `application/json`, HTTParty will parse the response and return Ruby objects such as a hash or array. The default behavior for parsing JSON will return keys as strings. This can be supressed with the `format` option. To get hash keys as symbols:
```ruby
response = HTTParty.get('http://example.com', format: :plain)
JSON.parse response, symbolize_names: true
```
## Posting JSON
When using Content Type `application/json` with `POST`, `PUT` or `PATCH` requests, the body should be a string of valid JSON:
```ruby
# With written JSON
HTTParty.post('http://example.com', body: "{\"foo\":\"bar\"}", headers: { 'Content-Type' => 'application/json' })
# Using JSON.generate
HTTParty.post('http://example.com', body: JSON.generate({ foo: 'bar' }), headers: { 'Content-Type' => 'application/json' })
# Using object.to_json
HTTParty.post('http://example.com', body: { foo: 'bar' }.to_json, headers: { 'Content-Type' => 'application/json' })
```
## Working with SSL
You can use this guide to work with SSL certificates.
#### Using `pem` option
```ruby
# Use this example if you are using a pem file
class Client
include HTTParty
base_uri "https://example.com"
pem File.read("#{File.expand_path('.')}/path/to/certs/cert.pem"), "123456"
end
```
#### Using `pkcs12` option
```ruby
# Use this example if you are using a pkcs12 file
class Client
include HTTParty
base_uri "https://example.com"
pkcs12 File.read("#{File.expand_path('.')}/path/to/certs/cert.p12"), "123456"
end
```
#### Using `ssl_ca_file` option
```ruby
# Use this example if you are using a pkcs12 file
class Client
include HTTParty
base_uri "https://example.com"
ssl_ca_file "#{File.expand_path('.')}/path/to/certs/cert.pem"
end
```
#### Using `ssl_ca_path` option
```ruby
# Use this example if you are using a pkcs12 file
class Client
include HTTParty
base_uri "https://example.com"
ssl_ca_path '/path/to/certs'
end
```
You can also include all of these options with the call:
```ruby
class Client
include HTTParty
base_uri "https://example.com"
def self.fetch
get("/resources", pem: File.read("#{File.expand_path('.')}/path/to/certs/cert.pem"), pem_password: "123456")
end
end
```
### Avoid SSL verification
In some cases you may want to skip SSL verification, because the entity that issued the certificate is not a valid one, but you still want to work with it. You can achieve this through:
```ruby
# Skips SSL certificate verification
class Client
include HTTParty
base_uri "https://example.com"
pem File.read("#{File.expand_path('.')}/path/to/certs/cert.pem"), "123456"
def self.fetch
get("/resources", verify: false)
# You can also use something like:
# get("resources", verify_peer: false)
end
end
```
### HTTP Compression
The `Accept-Encoding` request header and `Content-Encoding` response header
are used to control compression (gzip, etc.) over the wire. Refer to
[RFC-2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) for details.
(For clarity: these headers are **not** used for character encoding i.e. `utf-8`
which is specified in the `Accept` and `Content-Type` headers.)
Unless you have specific requirements otherwise, we recommend to **not** set
set the `Accept-Encoding` header on HTTParty requests. In this case, `Net::HTTP`
will set a sensible default compression scheme and automatically decompress the response.
If you explicitly set `Accept-Encoding`, there be dragons:
* If the HTTP response `Content-Encoding` received on the wire is `gzip` or `deflate`,
`Net::HTTP` will automatically decompress it, and will omit `Content-Encoding`
from your `HTTParty::Response` headers.
* For the following encodings, HTTParty will automatically decompress them if you include
the required gem into your project. Similar to above, if decompression succeeds,
`Content-Encoding` will be omitted from your `HTTParty::Response` headers.
**Warning:** Support for these encodings is experimental and not fully battle-tested.
| Content-Encoding | Required Gem |
| --- | --- |
| `br` (Brotli) | [brotli](https://rubygems.org/gems/brotli) |
| `compress` (LZW) | [ruby-lzws](https://rubygems.org/gems/ruby-lzws) |
| `zstd` (Zstandard) | [zstd-ruby](https://rubygems.org/gems/zstd-ruby) |
* For other encodings, `HTTParty::Response#body` will return the raw uncompressed byte string,
and you'll need to inspect the `Content-Encoding` response header and decompress it yourself.
In this case, `HTTParty::Response#parsed_response` will be `nil`.
* Lastly, you may use the `skip_decompression` option to disable all automatic decompression
and always get `HTTParty::Response#body` in its raw form along with the `Content-Encoding` header.
```ruby
# Accept-Encoding=gzip,deflate can be safely assumed to be auto-decompressed
res = HTTParty.get('https://example.com/test.json', headers: { 'Accept-Encoding' => 'gzip,deflate,identity' })
JSON.parse(res.body) # safe
# Accept-Encoding=br,compress requires third-party gems
require 'brotli'
require 'lzws'
require 'zstd-ruby'
res = HTTParty.get('https://example.com/test.json', headers: { 'Accept-Encoding' => 'br,compress,zstd' })
JSON.parse(res.body)
# Accept-Encoding=* may return unhandled Content-Encoding
res = HTTParty.get('https://example.com/test.json', headers: { 'Accept-Encoding' => '*' })
encoding = res.headers['Content-Encoding']
if encoding
JSON.parse(your_decompression_handling(res.body, encoding))
else
# Content-Encoding not present implies decompressed
JSON.parse(res.body)
end
# Gimme the raw data!
res = HTTParty.get('https://example.com/test.json', skip_decompression: true)
encoding = res.headers['Content-Encoding']
JSON.parse(your_decompression_handling(res.body, encoding))
```
|
