crapi 0.1.3 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (37) hide show
  1. checksums.yaml +4 -4
  2. data/.circleci/config.yml +63 -0
  3. data/.rubocop.yml +53 -70
  4. data/.ruby-version +1 -1
  5. data/Gemfile.lock +66 -42
  6. data/README.md +29 -27
  7. data/crapi.gemspec +15 -15
  8. data/docs/{Crapi → CrAPI}/ArgumentError.html +15 -16
  9. data/docs/{Crapi → CrAPI}/BadHttpResponseError.html +15 -16
  10. data/docs/{Crapi → CrAPI}/Client.html +144 -174
  11. data/docs/{Crapi → CrAPI}/Error.html +14 -15
  12. data/docs/{Crapi → CrAPI}/Proxy.html +65 -89
  13. data/docs/CrAPI.html +157 -0
  14. data/docs/Net/HTTP.html +18 -23
  15. data/docs/_index.html +19 -19
  16. data/docs/class_list.html +3 -3
  17. data/docs/css/style.css +7 -9
  18. data/docs/file.README.html +68 -87
  19. data/docs/file_list.html +2 -2
  20. data/docs/frames.html +2 -2
  21. data/docs/index.html +68 -87
  22. data/docs/js/app.js +69 -3
  23. data/docs/method_list.html +34 -34
  24. data/docs/top-level-namespace.html +8 -8
  25. data/lib/crapi/client.rb +224 -228
  26. data/lib/crapi/errors.rb +7 -7
  27. data/lib/crapi/proxy.rb +82 -82
  28. data/lib/crapi/version.rb +10 -10
  29. data/lib/crapi.rb +3 -1
  30. data/spec/crapi_client_spec.rb +121 -0
  31. data/spec/crapi_errors_spec.rb +17 -0
  32. data/spec/crapi_proxy_spec.rb +121 -0
  33. data/spec/crapi_spec.rb +5 -0
  34. data/spec/spec_helper.rb +19 -0
  35. metadata +66 -52
  36. data/.travis.yml +0 -5
  37. data/docs/Crapi.html +0 -153
data/docs/file.README.html CHANGED
@@ -6,15 +6,15 @@
6
6
  <title>
7
7
  File: README
8
8
 
9
- &mdash; Documentation by YARD 0.9.12
9
+ &mdash; Documentation by YARD 0.9.28
10
10
 
11
11
  </title>
12
12
 
13
- <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
14
 
15
- <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
16
 
17
- <script type="text/javascript" charset="utf-8">
17
+ <script type="text/javascript">
18
18
  pathId = "README";
19
19
  relpath = '';
20
20
  </script>
@@ -57,29 +57,22 @@
57
57
  <div class="clear"></div>
58
58
  </div>
59
59
 
60
- <div id="content"><div id='filecontents'>
61
- <h1 id="label-Crapi+rdoc-image-3Ahttps-3A-2F-2Fbadge.fury.io-2Frb-2Fcrapi.svg">Crapi <a href="https://badge.fury.io/rb/crapi"><img src="https://badge.fury.io/rb/crapi.svg"></a></h1>
60
+ <div id="content"><div id='filecontents'><p><a href="https://rubygems.org/gems/crapi"><img src="https://img.shields.io/github/v/release/nestor-custodio/crapi?color=green&amp;label=gem%20version" alt="Gem Version" /></a>
61
+ <a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/github/license/nestor-custodio/crapi" alt="MIT License" /></a></p>
62
62
 
63
- <p>Crapi is yet another API wrapper. Yes, there is no shortage of these out
64
- there, but no other API wrapper gem (that I could find) provided the kind
65
- of functionality you get from the Crapi::Proxy class, which is really the
66
- biggest benefit here.</p>
63
+ <h1 id="crapi">CrAPI</h1>
67
64
 
68
- <p><strong>Crapi::Client</strong> will connect to the target system and
69
- handily provides a base path for you (becaue some APIs and services have a
70
- path that is always part of every request), <strong>Crapi::Proxy</strong>
71
- lets you add to the root client&#39;s base path or default set of headers
72
- without having to create any new connections.</p>
65
+ <p>CrAPI is yet another <u>Cr</u>ud <u>API</u> client wrapper. Yes, there is no shortage of these out there, but no other API wrapper gem (that I could find) provided the kind of functionality you get from the CrAPI::Proxy class, which is really the biggest benefit here.</p>
73
66
 
74
- <p>Why “crapi”? Because it&#39;s a &lt;u&gt;CR&lt;/u&gt;UD
75
- &lt;u&gt;API&lt;/u&gt; client, and (honestly) “… It could be better.”™️</p>
67
+ <p><strong>CrAPI::Client</strong> will connect to the target system and handily provides a base path for you (because some APIs and services have a path that is always part of every request), <strong>CrAPI::Proxy</strong> lets you add to the root client’s base path or default set of headers without having to create any new connections.</p>
76
68
 
77
- <h2 id="label-Installation">Installation</h2>
69
+ <h2 id="installation">Installation</h2>
78
70
 
79
- <p>Add this line to your application&#39;s Gemfile:</p>
71
+ <p>Add this line to your application’s Gemfile:</p>
80
72
 
81
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>crapi</span><span class='tstring_end'>&#39;</span></span>
82
- </code></pre>
73
+ <p><code>ruby
74
+ gem 'crapi'
75
+ </code></p>
83
76
 
84
77
  <p>And then execute:</p>
85
78
 
@@ -91,99 +84,87 @@ without having to create any new connections.</p>
91
84
  <pre class="code ruby"><code class="ruby">$ gem install crapi
92
85
  </code></pre>
93
86
 
94
- <h2 id="label-Using+The+Crapi+Tools">Using The Crapi Tools</h2>
87
+ <h2 id="using-the-crapi-tools">Using The CrAPI Tools</h2>
88
+
89
+ <h3 id="client-usage">Client Usage</h3>
90
+
91
+ <p>```ruby
92
+ # Connect to an API.</p>
93
+
94
+ <p>api = CrAPI::Client.new(‘https://jsonplaceholder.typicode.com/’)</p>
95
+
96
+ <h1 id="issue-requests-against-the-api">Issue requests against the API.</h1>
95
97
 
96
- <h3 id="label-Client+Usage">Client Usage</h3>
98
+ <p>api.get(‘users/1’) # GETs /users/1; returns a Hash.</p>
97
99
 
98
- <pre class="code ruby"><code class="ruby"><span class='comment'>## Connect to an API.
99
- </span>
100
- <span class='id identifier rubyid_api'>api</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Crapi.html" title="Crapi (module)">Crapi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Crapi/Client.html" title="Crapi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Crapi/Client.html#initialize-instance_method" title="Crapi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://jsonplaceholder.typicode.com/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
100
+ <p>api.get(‘posts’, query: { userId: 2 }) # GETs /posts?userId=2; returns an Array.</p>
101
101
 
102
+ <p>mew_comment = { user: ‘megapwner’, text: ‘FRIST!!1!’ }
103
+ api.post(‘comments’, payload: new_comment) # POSTs to /comments; returns a Hash.
104
+ ```</p>
102
105
 
103
- <span class='comment'>## Issue requests against the API.
104
- </span>
105
- <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>users/1</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /users/1; returns a Hash.
106
- </span>
107
- <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>posts</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>query:</span> <span class='lbrace'>{</span> <span class='label'>userId:</span> <span class='int'>2</span> <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='comment'>## GETs /posts?userId=2; returns an Array.
108
- </span>
109
- <span class='id identifier rubyid_mew_comment'>mew_comment</span> <span class='op'>=</span> <span class='lbrace'>{</span> <span class='label'>user:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>megapwner</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>text:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>FRIST!!1!</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
110
- <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_post'>post</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>comments</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>payload:</span> <span class='id identifier rubyid_new_comment'>new_comment</span><span class='rparen'>)</span> <span class='comment'>## POSTs to /comments; returns a Hash.
111
- </span></code></pre>
112
- <hr>
106
+ <hr />
113
107
 
114
- <h3 id="label-Proxy+Usage">Proxy Usage</h3>
108
+ <h3 id="proxy-usage">Proxy Usage</h3>
115
109
 
116
- <pre class="code ruby"><code class="ruby"><span class='comment'>## Connect to an API.
117
- </span>
118
- <span class='id identifier rubyid_api'>api</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Crapi.html" title="Crapi (module)">Crapi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Crapi/Client.html" title="Crapi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Crapi/Client.html#initialize-instance_method" title="Crapi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://versioned.fake-api.com/api/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
110
+ <p>```ruby
111
+ # Connect to an API.</p>
119
112
 
113
+ <p>api = CrAPI::Client.new(‘https://versioned.fake-api.com/api/’)</p>
120
114
 
121
- <span class='comment'>## Back in the v1 days, versioning of this API was via the URL ...
122
- </span>
123
- <span class='id identifier rubyid_v1'>v1</span> <span class='op'>=</span> <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_new_proxy'>new_proxy</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/v1</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
115
+ <h1 id="back-in-the-v1-days-versioning-of-this-api-was-via-the-url-">Back in the v1 days, versioning of this API was via the URL …</h1>
124
116
 
125
- <span class='id identifier rubyid_v1'>v1</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /api/v1/data; pretty straight-forward.
126
- </span><span class='id identifier rubyid_v1'>v1</span><span class='period'>.</span><span class='id identifier rubyid_post'>post</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>payload:</span> <span class='id identifier rubyid_values'>values</span><span class='rparen'>)</span> <span class='comment'>## POSTs *values* to /api/v1/data.
127
- </span>
117
+ <p>v1 = api.new_proxy(‘/v1’)</p>
128
118
 
129
- <span class='comment'>## For API v2, they switched to an Accept header approach ...
130
- </span>
131
- <span class='id identifier rubyid_v2'>v2</span> <span class='op'>=</span> <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_new_proxy'>new_proxy</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='label'>Accept:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>application/vnd.fake-api.v2+json</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span>
119
+ <p>v1.get(‘data’) # GETs /api/v1/data; pretty straight-forward.
120
+ v1.post(‘data’, payload: values) # POSTs <em>values</em> to /api/v1/data.</p>
132
121
 
133
- <span class='id identifier rubyid_v2'>v2</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /api/data with the v2 header.
134
- </span>
122
+ <h1 id="for-api-v2-they-switched-to-an-accept-header-approach-">For API v2, they switched to an Accept header approach …</h1>
135
123
 
136
- <span class='comment'>## API v3 keeps the Accept header approach ...
137
- </span>
138
- <span class='id identifier rubyid_v3'>v3</span> <span class='op'>=</span> <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_new_proxy'>new_proxy</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='label'>Accept:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>application/vnd.fake-api.v3+json</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span>
124
+ <p>v2 = api.new_proxy(‘/’, headers: { Accept: ‘application/vnd.fake-api.v2+json’ })</p>
139
125
 
140
- <span class='id identifier rubyid_v3'>v3</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /api/data with the v3 header.
141
- </span>
126
+ <p>v2.get(‘data’) # GETs /api/data with the v2 header.</p>
142
127
 
143
- <span class='comment'>## Note that only one connection to the client is made and you can easily make
144
- </span><span class='comment'>## v1, v2, and v3 API calls ad hoc without having to juggle paths/headers yourself.
145
- </span></code></pre>
146
- <hr>
128
+ <h1 id="api-v3-keeps-the-accept-header-approach-">API v3 keeps the Accept header approach …</h1>
147
129
 
148
- <p><a href="http://nestor-custodio.github.io/crapi/Crapi.html">Consult the
149
- repo docs for the full Crapi documentation.</a></p>
130
+ <p>v3 = api.new_proxy(‘/’, headers: { Accept: ‘application/vnd.fake-api.v3+json’ })</p>
150
131
 
151
- <h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
132
+ <p>v3.get(‘data’) # GETs /api/data with the v3 header.</p>
133
+
134
+ <h1 id="note-that-only-one-connection-to-the-client-is-made-and-you-can-easily-make">Note that only one connection to the client is made and you can easily make</h1>
135
+ <p># v1, v2, and v3 API calls ad hoc without having to juggle paths/headers yourself.
136
+ ```</p>
137
+
138
+ <hr />
139
+
140
+ <p><a href="http://nestor-custodio.github.io/crapi/CrAPI.html">Consult the repo docs for the full CrAPI documentation.</a></p>
141
+
142
+ <h2 id="feature-roadmap--future-development">Feature Roadmap / Future Development</h2>
152
143
 
153
144
  <p>Additional features/options coming in the future:</p>
154
- <ul><li>
155
- <p>Cleaner handling of non-body-returning calls.</p>
156
- </li><li>
157
- <p>More resilient serializing of non-String paylods when using custom
158
- Content-Type headers.</p>
159
- </li></ul>
160
145
 
161
- <h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
146
+ <ul>
147
+ <li>Cleaner handling of non-body-returning calls.</li>
148
+ <li>More resilient serializing of non-String paylods when using custom Content-Type headers.</li>
149
+ </ul>
150
+
151
+ <h2 id="contribution--development">Contribution / Development</h2>
162
152
 
163
- <p>Bug reports and pull requests are welcome on GitHub at <a
164
- href="https://github.com/nestor-custodio/crapi">github.com/nestor-custodio/crapi</a>.</p>
153
+ <p>Bug reports and pull requests are welcome at: <a href="https://github.com/nestor-custodio/crapi">https://github.com/nestor-custodio/crapi</a></p>
165
154
 
166
- <p>After checking out the repo, run <code>bin/setup</code> to install
167
- dependencies. Then, run <code>rake spec</code> to run the tests. You can
168
- also run <code>bin/console</code> for an interactive prompt that will allow
169
- you to experiment.</p>
155
+ <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>bundle exec rspec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
170
156
 
171
- <p>Linting is courtesy of <a
172
- href="https://github.com/bbatsov/rubocop">Rubocop</a> and documentation is
173
- built using <a href="https://yardoc.org/">Yard</a>. Neither is included in
174
- the Gemspec; you&#39;ll need to install these locally (<code>gem install
175
- rubocop yard</code>) to take advantage.</p>
157
+ <p>Linting is courtesy of <a href="https://docs.rubocop.org/">Rubocop</a> (<code>bundle exec rubocop</code>) and documentation is built using <a href="https://yardoc.org/">Yard</a> (<code>bundle exec yard</code>). Please ensure you have a clean bill of health from Rubocop and that any new features and/or changes to behaviour are reflected in the documentation before submitting a pull request.</p>
176
158
 
177
- <h2 id="label-License">License</h2>
159
+ <h2 id="license">License</h2>
178
160
 
179
- <p>The gem is available as open source under the terms of the <a
180
- href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
161
+ <p>CrAPI is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p>
181
162
  </div></div>
182
163
 
183
164
  <div id="footer">
184
- Generated on Wed May 30 16:20:53 2018 by
185
- <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
186
- 0.9.12 (ruby-2.5.1).
165
+ Generated on Mon Jan 2 15:16:45 2023 by
166
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
167
+ 0.9.28 (ruby-3.0.4).
187
168
  </div>
188
169
 
189
170
  </div>
data/docs/file_list.html CHANGED
@@ -4,9 +4,9 @@
4
4
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
5
5
  <meta charset="utf-8" />
6
6
 
7
- <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" />
8
8
 
9
- <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" />
10
10
 
11
11
 
12
12
 
data/docs/frames.html CHANGED
@@ -2,9 +2,9 @@
2
2
  <html>
3
3
  <head>
4
4
  <meta charset="utf-8">
5
- <title>Documentation by YARD 0.9.12</title>
5
+ <title>Documentation by YARD 0.9.28</title>
6
6
  </head>
7
- <script type="text/javascript" charset="utf-8">
7
+ <script type="text/javascript">
8
8
  var match = unescape(window.location.hash).match(/^#!(.+)/);
9
9
  var name = match ? match[1] : 'index.html';
10
10
  name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');
data/docs/index.html CHANGED
@@ -6,15 +6,15 @@
6
6
  <title>
7
7
  File: README
8
8
 
9
- &mdash; Documentation by YARD 0.9.12
9
+ &mdash; Documentation by YARD 0.9.28
10
10
 
11
11
  </title>
12
12
 
13
- <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" />
14
14
 
15
- <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" />
16
16
 
17
- <script type="text/javascript" charset="utf-8">
17
+ <script type="text/javascript">
18
18
  pathId = "README";
19
19
  relpath = '';
20
20
  </script>
@@ -57,29 +57,22 @@
57
57
  <div class="clear"></div>
58
58
  </div>
59
59
 
60
- <div id="content"><div id='filecontents'>
61
- <h1 id="label-Crapi+rdoc-image-3Ahttps-3A-2F-2Fbadge.fury.io-2Frb-2Fcrapi.svg">Crapi <a href="https://badge.fury.io/rb/crapi"><img src="https://badge.fury.io/rb/crapi.svg"></a></h1>
60
+ <div id="content"><div id='filecontents'><p><a href="https://rubygems.org/gems/crapi"><img src="https://img.shields.io/github/v/release/nestor-custodio/crapi?color=green&amp;label=gem%20version" alt="Gem Version" /></a>
61
+ <a href="https://tldrlegal.com/license/mit-license"><img src="https://img.shields.io/github/license/nestor-custodio/crapi" alt="MIT License" /></a></p>
62
62
 
63
- <p>Crapi is yet another API wrapper. Yes, there is no shortage of these out
64
- there, but no other API wrapper gem (that I could find) provided the kind
65
- of functionality you get from the Crapi::Proxy class, which is really the
66
- biggest benefit here.</p>
63
+ <h1 id="crapi">CrAPI</h1>
67
64
 
68
- <p><strong>Crapi::Client</strong> will connect to the target system and
69
- handily provides a base path for you (becaue some APIs and services have a
70
- path that is always part of every request), <strong>Crapi::Proxy</strong>
71
- lets you add to the root client&#39;s base path or default set of headers
72
- without having to create any new connections.</p>
65
+ <p>CrAPI is yet another <u>Cr</u>ud <u>API</u> client wrapper. Yes, there is no shortage of these out there, but no other API wrapper gem (that I could find) provided the kind of functionality you get from the CrAPI::Proxy class, which is really the biggest benefit here.</p>
73
66
 
74
- <p>Why “crapi”? Because it&#39;s a &lt;u&gt;CR&lt;/u&gt;UD
75
- &lt;u&gt;API&lt;/u&gt; client, and (honestly) “… It could be better.”™️</p>
67
+ <p><strong>CrAPI::Client</strong> will connect to the target system and handily provides a base path for you (because some APIs and services have a path that is always part of every request), <strong>CrAPI::Proxy</strong> lets you add to the root client’s base path or default set of headers without having to create any new connections.</p>
76
68
 
77
- <h2 id="label-Installation">Installation</h2>
69
+ <h2 id="installation">Installation</h2>
78
70
 
79
- <p>Add this line to your application&#39;s Gemfile:</p>
71
+ <p>Add this line to your application’s Gemfile:</p>
80
72
 
81
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>crapi</span><span class='tstring_end'>&#39;</span></span>
82
- </code></pre>
73
+ <p><code>ruby
74
+ gem 'crapi'
75
+ </code></p>
83
76
 
84
77
  <p>And then execute:</p>
85
78
 
@@ -91,99 +84,87 @@ without having to create any new connections.</p>
91
84
  <pre class="code ruby"><code class="ruby">$ gem install crapi
92
85
  </code></pre>
93
86
 
94
- <h2 id="label-Using+The+Crapi+Tools">Using The Crapi Tools</h2>
87
+ <h2 id="using-the-crapi-tools">Using The CrAPI Tools</h2>
88
+
89
+ <h3 id="client-usage">Client Usage</h3>
90
+
91
+ <p>```ruby
92
+ # Connect to an API.</p>
93
+
94
+ <p>api = CrAPI::Client.new(‘https://jsonplaceholder.typicode.com/’)</p>
95
+
96
+ <h1 id="issue-requests-against-the-api">Issue requests against the API.</h1>
95
97
 
96
- <h3 id="label-Client+Usage">Client Usage</h3>
98
+ <p>api.get(‘users/1’) # GETs /users/1; returns a Hash.</p>
97
99
 
98
- <pre class="code ruby"><code class="ruby"><span class='comment'>## Connect to an API.
99
- </span>
100
- <span class='id identifier rubyid_api'>api</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Crapi.html" title="Crapi (module)">Crapi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Crapi/Client.html" title="Crapi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Crapi/Client.html#initialize-instance_method" title="Crapi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://jsonplaceholder.typicode.com/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
100
+ <p>api.get(‘posts’, query: { userId: 2 }) # GETs /posts?userId=2; returns an Array.</p>
101
101
 
102
+ <p>mew_comment = { user: ‘megapwner’, text: ‘FRIST!!1!’ }
103
+ api.post(‘comments’, payload: new_comment) # POSTs to /comments; returns a Hash.
104
+ ```</p>
102
105
 
103
- <span class='comment'>## Issue requests against the API.
104
- </span>
105
- <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>users/1</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /users/1; returns a Hash.
106
- </span>
107
- <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>posts</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>query:</span> <span class='lbrace'>{</span> <span class='label'>userId:</span> <span class='int'>2</span> <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='comment'>## GETs /posts?userId=2; returns an Array.
108
- </span>
109
- <span class='id identifier rubyid_mew_comment'>mew_comment</span> <span class='op'>=</span> <span class='lbrace'>{</span> <span class='label'>user:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>megapwner</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>text:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>FRIST!!1!</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
110
- <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_post'>post</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>comments</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>payload:</span> <span class='id identifier rubyid_new_comment'>new_comment</span><span class='rparen'>)</span> <span class='comment'>## POSTs to /comments; returns a Hash.
111
- </span></code></pre>
112
- <hr>
106
+ <hr />
113
107
 
114
- <h3 id="label-Proxy+Usage">Proxy Usage</h3>
108
+ <h3 id="proxy-usage">Proxy Usage</h3>
115
109
 
116
- <pre class="code ruby"><code class="ruby"><span class='comment'>## Connect to an API.
117
- </span>
118
- <span class='id identifier rubyid_api'>api</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Crapi.html" title="Crapi (module)">Crapi</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Crapi/Client.html" title="Crapi::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Crapi/Client.html#initialize-instance_method" title="Crapi::Client#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://versioned.fake-api.com/api/</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
110
+ <p>```ruby
111
+ # Connect to an API.</p>
119
112
 
113
+ <p>api = CrAPI::Client.new(‘https://versioned.fake-api.com/api/’)</p>
120
114
 
121
- <span class='comment'>## Back in the v1 days, versioning of this API was via the URL ...
122
- </span>
123
- <span class='id identifier rubyid_v1'>v1</span> <span class='op'>=</span> <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_new_proxy'>new_proxy</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/v1</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
115
+ <h1 id="back-in-the-v1-days-versioning-of-this-api-was-via-the-url-">Back in the v1 days, versioning of this API was via the URL …</h1>
124
116
 
125
- <span class='id identifier rubyid_v1'>v1</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /api/v1/data; pretty straight-forward.
126
- </span><span class='id identifier rubyid_v1'>v1</span><span class='period'>.</span><span class='id identifier rubyid_post'>post</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>payload:</span> <span class='id identifier rubyid_values'>values</span><span class='rparen'>)</span> <span class='comment'>## POSTs *values* to /api/v1/data.
127
- </span>
117
+ <p>v1 = api.new_proxy(‘/v1’)</p>
128
118
 
129
- <span class='comment'>## For API v2, they switched to an Accept header approach ...
130
- </span>
131
- <span class='id identifier rubyid_v2'>v2</span> <span class='op'>=</span> <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_new_proxy'>new_proxy</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='label'>Accept:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>application/vnd.fake-api.v2+json</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span>
119
+ <p>v1.get(‘data’) # GETs /api/v1/data; pretty straight-forward.
120
+ v1.post(‘data’, payload: values) # POSTs <em>values</em> to /api/v1/data.</p>
132
121
 
133
- <span class='id identifier rubyid_v2'>v2</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /api/data with the v2 header.
134
- </span>
122
+ <h1 id="for-api-v2-they-switched-to-an-accept-header-approach-">For API v2, they switched to an Accept header approach …</h1>
135
123
 
136
- <span class='comment'>## API v3 keeps the Accept header approach ...
137
- </span>
138
- <span class='id identifier rubyid_v3'>v3</span> <span class='op'>=</span> <span class='id identifier rubyid_api'>api</span><span class='period'>.</span><span class='id identifier rubyid_new_proxy'>new_proxy</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>headers:</span> <span class='lbrace'>{</span> <span class='label'>Accept:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>application/vnd.fake-api.v3+json</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span>
124
+ <p>v2 = api.new_proxy(‘/’, headers: { Accept: ‘application/vnd.fake-api.v2+json’ })</p>
139
125
 
140
- <span class='id identifier rubyid_v3'>v3</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>data</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>## GETs /api/data with the v3 header.
141
- </span>
126
+ <p>v2.get(‘data’) # GETs /api/data with the v2 header.</p>
142
127
 
143
- <span class='comment'>## Note that only one connection to the client is made and you can easily make
144
- </span><span class='comment'>## v1, v2, and v3 API calls ad hoc without having to juggle paths/headers yourself.
145
- </span></code></pre>
146
- <hr>
128
+ <h1 id="api-v3-keeps-the-accept-header-approach-">API v3 keeps the Accept header approach …</h1>
147
129
 
148
- <p><a href="http://nestor-custodio.github.io/crapi/Crapi.html">Consult the
149
- repo docs for the full Crapi documentation.</a></p>
130
+ <p>v3 = api.new_proxy(‘/’, headers: { Accept: ‘application/vnd.fake-api.v3+json’ })</p>
150
131
 
151
- <h2 id="label-Feature+Roadmap+-2F+Future+Development">Feature Roadmap / Future Development</h2>
132
+ <p>v3.get(‘data’) # GETs /api/data with the v3 header.</p>
133
+
134
+ <h1 id="note-that-only-one-connection-to-the-client-is-made-and-you-can-easily-make">Note that only one connection to the client is made and you can easily make</h1>
135
+ <p># v1, v2, and v3 API calls ad hoc without having to juggle paths/headers yourself.
136
+ ```</p>
137
+
138
+ <hr />
139
+
140
+ <p><a href="http://nestor-custodio.github.io/crapi/CrAPI.html">Consult the repo docs for the full CrAPI documentation.</a></p>
141
+
142
+ <h2 id="feature-roadmap--future-development">Feature Roadmap / Future Development</h2>
152
143
 
153
144
  <p>Additional features/options coming in the future:</p>
154
- <ul><li>
155
- <p>Cleaner handling of non-body-returning calls.</p>
156
- </li><li>
157
- <p>More resilient serializing of non-String paylods when using custom
158
- Content-Type headers.</p>
159
- </li></ul>
160
145
 
161
- <h2 id="label-Contribution+-2F+Development">Contribution / Development</h2>
146
+ <ul>
147
+ <li>Cleaner handling of non-body-returning calls.</li>
148
+ <li>More resilient serializing of non-String paylods when using custom Content-Type headers.</li>
149
+ </ul>
150
+
151
+ <h2 id="contribution--development">Contribution / Development</h2>
162
152
 
163
- <p>Bug reports and pull requests are welcome on GitHub at <a
164
- href="https://github.com/nestor-custodio/crapi">github.com/nestor-custodio/crapi</a>.</p>
153
+ <p>Bug reports and pull requests are welcome at: <a href="https://github.com/nestor-custodio/crapi">https://github.com/nestor-custodio/crapi</a></p>
165
154
 
166
- <p>After checking out the repo, run <code>bin/setup</code> to install
167
- dependencies. Then, run <code>rake spec</code> to run the tests. You can
168
- also run <code>bin/console</code> for an interactive prompt that will allow
169
- you to experiment.</p>
155
+ <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>bundle exec rspec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
170
156
 
171
- <p>Linting is courtesy of <a
172
- href="https://github.com/bbatsov/rubocop">Rubocop</a> and documentation is
173
- built using <a href="https://yardoc.org/">Yard</a>. Neither is included in
174
- the Gemspec; you&#39;ll need to install these locally (<code>gem install
175
- rubocop yard</code>) to take advantage.</p>
157
+ <p>Linting is courtesy of <a href="https://docs.rubocop.org/">Rubocop</a> (<code>bundle exec rubocop</code>) and documentation is built using <a href="https://yardoc.org/">Yard</a> (<code>bundle exec yard</code>). Please ensure you have a clean bill of health from Rubocop and that any new features and/or changes to behaviour are reflected in the documentation before submitting a pull request.</p>
176
158
 
177
- <h2 id="label-License">License</h2>
159
+ <h2 id="license">License</h2>
178
160
 
179
- <p>The gem is available as open source under the terms of the <a
180
- href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
161
+ <p>CrAPI is available as open source under the terms of the <a href="https://tldrlegal.com/license/mit-license">MIT License</a>.</p>
181
162
  </div></div>
182
163
 
183
164
  <div id="footer">
184
- Generated on Wed May 30 16:20:52 2018 by
185
- <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
186
- 0.9.12 (ruby-2.5.1).
165
+ Generated on Mon Jan 2 15:16:45 2023 by
166
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
167
+ 0.9.28 (ruby-3.0.4).
187
168
  </div>
188
169
 
189
170
  </div>
data/docs/js/app.js CHANGED
@@ -120,6 +120,49 @@ function summaryToggle() {
120
120
  } else { localStorage.summaryCollapsed = "expand"; }
121
121
  }
122
122
 
123
+ function constantSummaryToggle() {
124
+ $('.constants_summary_toggle').click(function(e) {
125
+ e.preventDefault();
126
+ localStorage.summaryCollapsed = $(this).text();
127
+ $('.constants_summary_toggle').each(function() {
128
+ $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
129
+ var next = $(this).parent().parent().nextAll('dl.constants').first();
130
+ if (next.hasClass('compact')) {
131
+ next.toggle();
132
+ next.nextAll('dl.constants').first().toggle();
133
+ }
134
+ else if (next.hasClass('constants')) {
135
+ var list = $('<dl class="constants compact" />');
136
+ list.html(next.html());
137
+ list.find('dt').each(function() {
138
+ $(this).addClass('summary_signature');
139
+ $(this).text( $(this).text().split('=')[0]);
140
+ if ($(this).has(".deprecated").length) {
141
+ $(this).addClass('deprecated');
142
+ };
143
+ });
144
+ // Add the value of the constant as "Tooltip" to the summary object
145
+ list.find('pre.code').each(function() {
146
+ console.log($(this).parent());
147
+ var dt_element = $(this).parent().prev();
148
+ var tooltip = $(this).text();
149
+ if (dt_element.hasClass("deprecated")) {
150
+ tooltip = 'Deprecated. ' + tooltip;
151
+ };
152
+ dt_element.attr('title', tooltip);
153
+ });
154
+ list.find('.docstring, .tags, dd').remove();
155
+ next.before(list);
156
+ next.toggle();
157
+ }
158
+ });
159
+ return false;
160
+ });
161
+ if (localStorage.summaryCollapsed == "collapse") {
162
+ $('.constants_summary_toggle').first().click();
163
+ } else { localStorage.summaryCollapsed = "expand"; }
164
+ }
165
+
123
166
  function generateTOC() {
124
167
  if ($('#filecontents').length === 0) return;
125
168
  var _toc = $('<ol class="top"></ol>');
@@ -128,6 +171,7 @@ function generateTOC() {
128
171
  var counter = 0;
129
172
  var tags = ['h2', 'h3', 'h4', 'h5', 'h6'];
130
173
  var i;
174
+ var curli;
131
175
  if ($('#filecontents h1').length > 1) tags.unshift('h1');
132
176
  for (i = 0; i < tags.length; i++) { tags[i] = '#filecontents ' + tags[i]; }
133
177
  var lastTag = parseInt(tags[0][1], 10);
@@ -147,15 +191,25 @@ function generateTOC() {
147
191
  }
148
192
  if (thisTag > lastTag) {
149
193
  for (i = 0; i < thisTag - lastTag; i++) {
150
- var tmp = $('<ol/>'); toc.append(tmp); toc = tmp;
194
+ if ( typeof(curli) == "undefined" ) {
195
+ curli = $('<li/>');
196
+ toc.append(curli);
197
+ }
198
+ toc = $('<ol/>');
199
+ curli.append(toc);
200
+ curli = undefined;
151
201
  }
152
202
  }
153
203
  if (thisTag < lastTag) {
154
- for (i = 0; i < lastTag - thisTag; i++) toc = toc.parent();
204
+ for (i = 0; i < lastTag - thisTag; i++) {
205
+ toc = toc.parent();
206
+ toc = toc.parent();
207
+ }
155
208
  }
156
209
  var title = $(this).attr('toc-title');
157
210
  if (typeof(title) == "undefined") title = $(this).text();
158
- toc.append('<li><a href="#' + this.id + '">' + title + '</a></li>');
211
+ curli =$('<li><a href="#' + this.id + '">' + title + '</a></li>');
212
+ toc.append(curli);
159
213
  lastTag = thisTag;
160
214
  });
161
215
  if (!show) return;
@@ -232,6 +286,16 @@ function mainFocus() {
232
286
  setTimeout(function() { $('#main').focus(); }, 10);
233
287
  }
234
288
 
289
+ function navigationChange() {
290
+ // This works around the broken anchor navigation with the YARD template.
291
+ window.onpopstate = function() {
292
+ var hash = window.location.hash;
293
+ if (hash !== '' && $(hash)[0]) {
294
+ $(hash)[0].scrollIntoView();
295
+ }
296
+ };
297
+ }
298
+
235
299
  $(document).ready(function() {
236
300
  navResizer();
237
301
  navExpander();
@@ -241,8 +305,10 @@ $(document).ready(function() {
241
305
  searchFrameButtons();
242
306
  linkSummaries();
243
307
  summaryToggle();
308
+ constantSummaryToggle();
244
309
  generateTOC();
245
310
  mainFocus();
311
+ navigationChange();
246
312
  });
247
313
 
248
314
  })();