|
1 | 1 | # JsonRequester |
2 | 2 |
|
3 | | -### A Wrapper of Faraday Gem |
| 3 | +[](https://badge.fury.io/rb/json_requester) |
4 | 4 |
|
5 | | -### Install |
| 5 | +`JsonRequester` is a lightweight wrapper around Faraday for sending |
| 6 | +JSON, form-encoded, and multipart HTTP requests. |
| 7 | + |
| 8 | +## Requirements |
| 9 | + |
| 10 | +- Ruby `>= 3.0.0` |
| 11 | +- Faraday `2.x` |
| 12 | + |
| 13 | +## Installation |
| 14 | + |
| 15 | +### For Faraday 2.x |
| 16 | + |
| 17 | +Install `json_requester` 2.x: |
6 | 18 |
|
7 | | -If you want to use faraday 1.x version, install json_requester 1.x version: |
8 | 19 | ```bash |
9 | | -$ gem install json_requester -v '~> 1.0' |
| 20 | +gem install json_requester -v '~> 2.0' |
10 | 21 | ``` |
11 | 22 |
|
12 | | -If you want to use faraday 2.x version, install json_requester 2.x version: |
| 23 | +### For Faraday 1.x |
| 24 | + |
| 25 | +If you still need Faraday 1.x, install `json_requester` 1.x: |
| 26 | + |
13 | 27 | ```bash |
14 | | -$ gem install json_requester -v '~> 2.0' |
| 28 | +gem install json_requester -v '~> 1.0' |
| 29 | +``` |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +### Initialize a requester |
| 34 | + |
| 35 | +```ruby |
| 36 | +host = 'http://httpbingo.org' |
| 37 | + |
| 38 | +requester = JsonRequester.new( |
| 39 | + host, |
| 40 | + timeout: 120, |
| 41 | + user_agent: 'My Agent 1.2' |
| 42 | +) |
15 | 43 | ``` |
16 | 44 |
|
17 | | -### How to Use |
| 45 | +Available initialization options: |
| 46 | + |
| 47 | +- `timeout`: request timeout in seconds, default is `60` |
| 48 | +- `user_agent`: custom user agent string |
| 49 | +- `multipart`: enable multipart request middleware, default is `false` |
| 50 | +- `ssl_verify`: enable SSL certificate verification, default is `true` |
| 51 | + |
| 52 | +### Send JSON requests |
| 53 | + |
| 54 | +Use `http_send` for regular JSON-based requests. |
| 55 | + |
| 56 | +- `:get` sends params as query parameters |
| 57 | +- other HTTP methods send params as a JSON body |
18 | 58 |
|
19 | 59 | ```ruby |
20 | | - # initialize the JsonRequester class |
21 | | - host = 'http://httpbingo.org' |
22 | | - # `timeout` at Faraday gem default is 60 secs. |
23 | | - # `user_agent` at Faraday gem default is like "Faraday v1.10.0", it would be deep_merge at Faraday default setting. |
24 | | - # `multipart` option enables multipart form requests (for file uploads), default is false |
25 | | - # `ssl_verify` controls SSL certificate verification, default is true |
26 | | - requester = JsonRequester.new(host, timeout: 120, user_agent: 'My Agent 1.2') |
27 | | - |
28 | | - http_method = :get # :get / :post / :put / :delete |
29 | | - path = '' |
30 | | - headers = { 'Authorization' => 'Bearer token' } |
31 | | - |
32 | | - # The `:get` method will use query params; |
33 | | - # Other HTTP methods will use JSON body to request. |
34 | | - params = { |
35 | | - key_1: 'value_1', |
36 | | - key_2: 'value_2' |
37 | | - } |
38 | | - |
39 | | - # Request by using JSON body or query params, use the `http_send` method. |
40 | | - # other methods: `form_send`, `multipart_form_send` |
41 | | - # `sort_params` at Faraday gem default is true. |
42 | | - # `content_type_charset` default is 'utf-8', this will add ; charset=utf-8 after `Content-Type` header (ex. `Content-Type=application/json; charset=utf-8`). |
43 | | - # `need_response_header` when set to true will include response headers in the result |
44 | | - res = requester.http_send(http_method, path, params, headers, sort_params: true, content_type_charset: 'utf-8') |
45 | | - |
46 | | - # http response code |
47 | | - puts res['status'] # 200, 404, .. etc |
48 | | - # the response JSON body |
49 | | - puts res['body'] # { foo: 'bar' } |
50 | | - # If need_response_header is true, you can access response headers |
51 | | - puts res['headers'] if res.key?('headers') |
52 | | - |
53 | | - # For form-encoded requests (application/x-www-form-urlencoded) |
54 | | - form_res = requester.form_send(:post, '/post', params, headers) |
55 | | - |
56 | | - # For file uploads or multipart form requests |
57 | | - # First initialize with multipart: true |
58 | | - multipart_requester = JsonRequester.new(host, multipart: true) |
59 | | - |
60 | | - # Then prepare your payload with file objects |
61 | | - upload_params = { |
62 | | - file: Faraday::Multipart::FilePart.new('path/to/file.txt', 'text/plain'), |
63 | | - description: 'File upload example' |
64 | | - } |
65 | | - |
66 | | - # Send multipart request |
67 | | - upload_res = multipart_requester.multipart_form_send(:post, '/upload_path', upload_params, headers) |
68 | | -``` |
| 60 | +path = '/post-path' |
| 61 | +headers = { 'Authorization' => 'Bearer token' } |
| 62 | +params = { |
| 63 | + key_1: 'value_1', |
| 64 | + key_2: 'value_2' |
| 65 | +} |
| 66 | + |
| 67 | +response = requester.http_send( |
| 68 | + :post, |
| 69 | + path, |
| 70 | + params, |
| 71 | + headers, |
| 72 | + sort_params: true, |
| 73 | + content_type_charset: 'utf-8', |
| 74 | + need_response_header: true |
| 75 | +) |
| 76 | + |
| 77 | +puts response['status'] |
| 78 | +puts response['body'] |
| 79 | +puts response['headers'] if response.key?('headers') |
| 80 | +``` |
| 81 | + |
| 82 | +### Send form-encoded requests |
| 83 | + |
| 84 | +Use `form_send` for `application/x-www-form-urlencoded` requests. |
| 85 | + |
| 86 | +```ruby |
| 87 | +path = '/post-path' |
| 88 | +headers = { 'Authorization' => 'Bearer token' } |
| 89 | +params = { |
| 90 | + key_1: 'value_1', |
| 91 | + key_2: 'value_2' |
| 92 | +} |
| 93 | + |
| 94 | +form_response = requester.form_send( |
| 95 | + :post, |
| 96 | + path, |
| 97 | + params, |
| 98 | + headers, |
| 99 | + sort_params: true, |
| 100 | + need_response_header: true |
| 101 | +) |
| 102 | +``` |
| 103 | + |
| 104 | +### Send multipart requests |
| 105 | + |
| 106 | +Use `multipart_form_send` for file uploads or multipart form data. |
| 107 | + |
| 108 | +```ruby |
| 109 | +multipart_requester = JsonRequester.new(host, multipart: true) |
| 110 | + |
| 111 | +upload_params = { |
| 112 | + file: Faraday::Multipart::FilePart.new('path/to/file.txt', 'text/plain'), |
| 113 | + description: 'File upload example' |
| 114 | +} |
| 115 | + |
| 116 | +upload_response = multipart_requester.multipart_form_send( |
| 117 | + :post, |
| 118 | + '/upload_path', |
| 119 | + upload_params, |
| 120 | + { 'Authorization' => 'Bearer token' } |
| 121 | +) |
| 122 | +``` |
| 123 | + |
| 124 | +## Request Methods |
| 125 | + |
| 126 | +- `http_send`: JSON body or query-parameter requests |
| 127 | +- `form_send`: form-encoded requests |
| 128 | +- `multipart_form_send`: multipart form requests |
| 129 | + |
| 130 | +### Method overview |
| 131 | + |
| 132 | +- `http_send`: uses query params for `:get`, and sends a JSON body for |
| 133 | + other HTTP methods |
| 134 | +- `form_send`: sends requests as `application/x-www-form-urlencoded` |
| 135 | +- `multipart_form_send`: sends multipart form data, typically for file |
| 136 | + uploads |
| 137 | + |
| 138 | +`http_send`, `form_send`, and `multipart_form_send` accept HTTP verbs |
| 139 | +such as: |
| 140 | + |
| 141 | +- `:get` |
| 142 | +- `:post` |
| 143 | +- `:put` |
| 144 | +- `:delete` |
| 145 | + |
| 146 | +### Common options |
| 147 | + |
| 148 | +- `sort_params`: controls whether query parameters are sorted before sending, default is `true` |
| 149 | +- `content_type_charset`: used by `http_send` for JSON requests, |
| 150 | + default is `'utf-8'` |
| 151 | +- `need_response_header`: when set to `true`, includes response |
| 152 | + headers in the returned result |
| 153 | + |
| 154 | +## Security |
| 155 | + |
| 156 | +Please see [SECURITY.md](SECURITY.md) for vulnerability reporting instructions. |
0 commit comments