hyperclient 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -2,8 +2,7 @@
2
2
 
3
3
  [![Gem Version](http://img.shields.io/gem/v/hyperclient.svg)](http://badge.fury.io/rb/hyperclient)
4
4
  [![Build Status](https://github.com/codegram/hyperclient/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/codegram/hyperclient/actions/workflows/test.yml)
5
- [![Code Climate](https://codeclimate.com/github/codegram/hyperclient.svg)](https://codeclimate.com/github/codegram/hyperclient)
6
- [![Coverage Status](https://img.shields.io/coveralls/codegram/hyperclient.svg)](https://coveralls.io/r/codegram/hyperclient?branch=master)
5
+ [![Coverage Status](https://coveralls.io/repos/github/codegram/hyperclient/badge.svg?branch=master)](https://coveralls.io/github/codegram/hyperclient?branch=master)
7
6
 
8
7
  Hyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON HAL](http://stateless.co/hal_specification.html).
9
8
 
@@ -14,9 +13,12 @@ Hyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON
14
13
  - [Resources and Attributes](#resources-and-attributes)
15
14
  - [Links and Embedded Resources](#links-and-embedded-resources)
16
15
  - [Templated Links](#templated-links)
16
+ - [Query Parameters](#query-parameters)
17
+ - [Link Properties](#link-properties)
17
18
  - [Curies](#curies)
18
19
  - [Attributes](#attributes)
19
20
  - [HTTP](#http)
21
+ - [Allowed Methods](#allowed-methods)
20
22
  - [Testing Using Hyperclient](#testing-using-hyperclient)
21
23
  - [Reference](#reference)
22
24
  - [Hyperclient Users](#hyperclient-users)
@@ -25,7 +27,9 @@ Hyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON
25
27
 
26
28
  # Usage
27
29
 
28
- The examples in this README use the [Splines Demo API](https://github.com/ruby-grape/grape-with-roar) running [here](https://grape-with-roar.herokuapp.com/api). Use version 1.x with Faraday 1.x, and version 2.x with Faraday 2.x. If you're upgrading from a previous version, please make sure to read [UPGRADING](UPGRADING.md).
30
+ The examples in this README use the [local Oxford HAL demo](examples/oxford/README.md), based on historical Oxford place facts. Start it with `bundle exec ruby examples/oxford/server.rb`, then run `bundle exec ruby -Ilib examples/oxford/client.rb` in another terminal. No external service is needed. Use version 1.x with Faraday 1.x, and version 2.x with Faraday 2.x. If you're upgrading from a previous version, please make sure to read [UPGRADING](UPGRADING.md).
31
+
32
+ Hyperclient is tested with JSON 2.x on Ruby 2.7, both JSON 2.x and 3.x on Ruby 3.2, and JSON 3.x on newer Rubies. JSON 3.x requires a Faraday release with keyword parser options support (2.14.4+).
29
33
 
30
34
  ## API Client
31
35
 
@@ -34,13 +38,13 @@ Create an API client.
34
38
  ```ruby
35
39
  require 'hyperclient'
36
40
 
37
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')
41
+ api = Hyperclient.new('http://127.0.0.1:9292/')
38
42
  ```
39
43
 
40
44
  By default, Hyperclient adds `application/hal+json` as `Content-Type` and `Accept` headers. It will also send requests as JSON and parse JSON responses. Specify additional headers or authentication if necessary.
41
45
 
42
46
  ```ruby
43
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
47
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
44
48
  client.headers['Access-Token'] = 'token'
45
49
  end
46
50
  ```
@@ -48,7 +52,7 @@ end
48
52
  Hyperclient constructs a connection using typical [Faraday](http://github.com/lostisland/faraday) middleware for handling JSON requests and responses. You can specify additional Faraday middleware if necessary.
49
53
 
50
54
  ```ruby
51
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
55
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
52
56
  client.connection do |conn|
53
57
  conn.use Faraday::Request::Instrumentation
54
58
  end
@@ -58,7 +62,7 @@ end
58
62
  You can pass options to the Faraday connection block in the `connection` block:
59
63
 
60
64
  ```ruby
61
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
65
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
62
66
  client.connection(ssl: { verify: false }) do |conn|
63
67
  conn.use Faraday::Request::Instrumentation
64
68
  end
@@ -68,7 +72,7 @@ end
68
72
  Or when using the default connection configuration you can use `faraday_options`:
69
73
 
70
74
  ```ruby
71
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
75
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
72
76
  client.faraday_options = { ssl: { verify: false } }
73
77
  end
74
78
  ```
@@ -76,7 +80,7 @@ end
76
80
  You can build a new Faraday connection block without inheriting default middleware by specifying `default: false` in the `connection` block.
77
81
 
78
82
  ```ruby
79
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
83
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
80
84
  client.connection(default: false) do |conn|
81
85
  conn.request :json
82
86
  conn.response :json, content_type: /\bjson$/
@@ -85,12 +89,14 @@ api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
85
89
  end
86
90
  ```
87
91
 
92
+ By default, Hyperclient requires responses to have a `Content-Type` of `application/hal+json`, and raises `Hyperclient::InvalidRepresentationError` otherwise. If your API sometimes returns responses that aren't `hal+json` (e.g. an empty body with a `201 Created`, or a plain `application/json` response), broaden the response middleware's `content_type` matcher as shown above (`content_type: /\bjson$/`) instead of the default, which only matches `hal+json`.
93
+
88
94
  You can modify headers or specify authentication after a connection has been created. Hyperclient supports Basic, Token or [Digest auth](https://github.com/bhaberer/faraday-digestauth) as well as many other Faraday extensions.
89
95
 
90
96
  ```ruby
91
97
  require 'faraday/digestauth'
92
98
 
93
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
99
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
94
100
  client.connection(default: false) do |conn|
95
101
  conn.request :digest, 'username', 'password'
96
102
  conn.request :json
@@ -103,7 +109,7 @@ end
103
109
  You can access the Faraday connection directly after it has been created and add middleware to it. As an example, you could use the [faraday-http-cache-middleware](https://github.com/plataformatec/faraday-http-cache).
104
110
 
105
111
  ```ruby
106
- api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')
112
+ api = Hyperclient.new('http://127.0.0.1:9292/')
107
113
  api.connection.use :http_cache
108
114
  ```
109
115
 
@@ -112,48 +118,82 @@ api.connection.use :http_cache
112
118
  Hyperclient will fetch and discover the resources from your API and automatically paginate when possible.
113
119
 
114
120
  ```ruby
115
- api.splines.each do |spline|
116
- puts "A spline with ID #{spline.uuid}."
121
+ api.places.each do |place|
122
+ puts "#{place.name} has ID #{place.id}."
117
123
  end
118
124
  ```
119
125
 
120
126
  Other methods, including `[]` and `fetch` are also available
121
127
 
122
128
  ```ruby
123
- api.splines.each do |spline|
124
- puts "A spline with ID #{spline[:uuid]}."
125
- puts "Maybe with reticulated: #{spline.fetch(:reticulated, '-- no reticulated')}"
129
+ api.places.each do |place|
130
+ puts "A place with ID #{place[:id]}."
131
+ puts "Address: #{place.fetch(:address, '-- no address')}"
126
132
  end
127
133
  ```
128
134
 
129
135
  ## Links and Embedded Resources
130
136
 
131
- The splines example above followed a link called "splines". While you can, you do not need to specify the HAL navigational structure, including links or embedded resources. Hyperclient will resolve these for you. If you prefer, you can explicitly navigate the link structure via `_links`. In the following example the "splines" link leads to a collection of embedded splines. Invoking `api.splines` is equivalent to `api._links.splines._embedded.splines`.
137
+ The example above follows the `places` link to a collection of embedded places. Hyperclient resolves links and embedded resources automatically. You can also navigate explicitly:
132
138
 
133
139
  ```ruby
134
- api._links.splines
140
+ api._links.places._embedded.places.each do |place|
141
+ puts place.name
142
+ end
143
+
144
+ place = api.place(id: 'oxpoints:23232339')
145
+ puts place.primary_place.name # follows a relative link to Balliol College
146
+ puts place._embedded.files.first.url # reads embedded metadata, without fetching the image
135
147
  ```
136
148
 
137
149
  ## Templated Links
138
150
 
139
- Templated links require variables to be expanded. For example, the demo API has a link called "spline" that requires a spline "uuid".
151
+ Templated links require variables to be expanded. The local demo adds a `place` link that accepts an Oxford place ID.
140
152
 
141
153
  ```ruby
142
- spline = api.spline(uuid: 'uuid')
143
- puts "Spline #{spline.uuid} is #{spline.reticulated ? 'reticulated' : 'not reticulated'}."
154
+ place = api.place(id: 'oxpoints:23232339')
155
+ puts place.name # => Balliol College
144
156
  ```
145
157
 
146
- Invoking `api.spline(uuid: 'uuid').reticulated` is equivalent to `api._links.spline._expand(uuid: 'uuid')._resource._attributes.reticulated`.
158
+ Invoking `api.place(id: 'oxpoints:23232339').name` is equivalent to `api._links.place._expand(id: 'oxpoints:23232339')._resource._attributes.name`.
147
159
 
148
160
  The client is responsible for supplying all the necessary parameters. Templated links don't do any strict parameter name checking and don't support required vs. optional parameters. Parameters not declared by the API will be dropped and will not have any effect when passed to `_expand`.
149
161
 
162
+ ## Query Parameters
163
+
164
+ HAL APIs declare the query parameters they accept in templated links, and `_expand` only fills in those. To send query parameters that a link doesn't declare, or to add them to a link that isn't templated, use `_query`. It returns a new link with the parameters appended to its URL, after any existing query string.
165
+
166
+ ```ruby
167
+ api._links.places._query(sort: 'name')._get # GET /places/?sort=name
168
+ api._links.place._expand(id: 'oxpoints:23232339')._query(fields: 'name')._get # GET /places/oxpoints%3A23232339?fields=name
169
+ ```
170
+
171
+ Array values are sent as repeated parameters, and parameters with `nil` values are dropped.
172
+
173
+ ## Link Properties
174
+
175
+ HAL links can carry optional [properties](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11#section-5) besides `href` and `templated`. Hyperclient exposes them as `_type`, `_deprecation`, `_name`, `_profile`, `_title`, and `_hreflang`, each returning `nil` when the property is absent. The local demo gives its `places` link a `title` and a `profile`.
176
+
177
+ ```ruby
178
+ puts api._links.places._title # => Oxford places
179
+ puts api._links.places._profile # => /docs/places
180
+ ```
181
+
182
+ A [`profile`](https://datatracker.ietf.org/doc/html/rfc6906) is a URI that documents the semantics of the target resource, beyond what the media type describes. Hyperclient returns it as-is and doesn't follow it, since a profile isn't necessarily a HAL resource. Fetch it with the client's Faraday connection if you need it.
183
+
184
+ ```ruby
185
+ puts api.connection.get(api._links.places._profile).body['description'] # => Archived Oxford place facts in a local HAL collection.
186
+ ```
187
+
188
+ A link with a `deprecation` property will be removed in the future, and `_deprecation` returns a URL with more information about the deprecation.
189
+
150
190
  ## Curies
151
191
 
152
- Curies are a suggested means by which to link documentation of a given resource. For example, the demo API contains very long links to images that use an "images" curie.
192
+ Curies provide compact names for relation documentation. The local demo adds an `oxford` CURIE and an `oxford:places` relation.
153
193
 
154
194
  ```ruby
155
- puts spline['image:thumbnail'] # => https://grape-with-roar.herokuapp.com/api/splines/uuid/images/thumbnail.jpg
156
- puts spline.links._curies['image'].expand('thumbnail') # => /docs/images/thumbnail
195
+ puts api._links['oxford:places']._embedded.places.first.name # => Balliol College
196
+ puts api._links._curies['oxford'].expand('places') # => /docs/places
157
197
  ```
158
198
 
159
199
  ## Attributes
@@ -161,10 +201,10 @@ puts spline.links._curies['image'].expand('thumbnail') # => /docs/images/thumbna
161
201
  Resource attributes can also be accessed as a hash.
162
202
 
163
203
  ```ruby
164
- puts spline.to_h # => {"uuid" => "uuid", "reticulated" => true}
204
+ puts place.to_h['name'] # => Balliol College
165
205
  ```
166
206
 
167
- The above is equivalent to `spline._attributes.to_h`.
207
+ `place.to_h` is equivalent to `place._attributes.to_h`.
168
208
 
169
209
  ## HTTP
170
210
 
@@ -180,35 +220,64 @@ api._response.body
180
220
  Other methods, including `_head` or `_options` are also available.
181
221
 
182
222
  ```ruby
183
- spline = api.spline(uuid: 'uuid')
184
- spline._head
185
- spline._options
223
+ place = api.place(id: 'oxpoints:23232339')
224
+ place._head
186
225
  ```
187
226
 
188
- Invoke `_post` to create resources.
227
+ The Oxford demo is read-only and rejects writes with HTTP 405. On a writable API, invoke `_post` to create resources:
189
228
 
190
229
  ```ruby
191
- splines = api.splines
192
- splines._post(uuid: 'new uuid', reticulated: false)
230
+ api.places._post(name: 'New place')
193
231
  ```
194
232
 
195
233
  Invoke `_put` or `_patch` to update resources.
196
234
 
197
235
  ```ruby
198
- spline = api.spline(uuid: 'uuid')
199
- spline._put(reticulated: true)
200
- spline._patch(reticulated: true)
236
+ place._put(name: 'Updated place')
237
+ place._patch(name: 'Updated place')
201
238
  ```
202
239
 
203
240
  Invoke `_delete` to destroy a resource.
204
241
 
205
242
  ```
206
- spline = api.spline(uuid: 'uuid')
207
- spline._delete
243
+ place._delete
208
244
  ```
209
245
 
210
246
  HTTP methods always return a new instance of Resource.
211
247
 
248
+ ## Allowed Methods
249
+
250
+ Hyperclient remembers the `Allow` header of the most recent response on the link that made the request, including a `405 Method Not Allowed` response, whose `Allow` header lists the methods the server supports. Each response replaces what the link knows. Use `_allow` and `_allow?` to check before sending a request.
251
+
252
+ ```ruby
253
+ order = api.order(id: 1) # a server responding with "Allow: GET, HEAD, OPTIONS"
254
+ order._get
255
+ order._allow # => ["GET", "HEAD", "OPTIONS"], or nil without an Allow header
256
+ order._allow?(:delete) # => false
257
+ ```
258
+
259
+ By default, Hyperclient still sends any method and leaves it to the server to refuse it. Set `enforce_allowed_methods` to have links refuse to send a method that their most recent `Allow` header doesn't list, raising `Hyperclient::MethodNotAllowedError` without contacting the server. A response without an `Allow` header lifts the restriction, and `_options` is always sent so you can rediscover the allowed methods.
260
+
261
+ ```ruby
262
+ api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
263
+ client.enforce_allowed_methods = true
264
+ end
265
+
266
+ order = api.order(id: 1) # a server responding with "Allow: GET, HEAD, OPTIONS"
267
+ order._get
268
+
269
+ begin
270
+ order._delete
271
+ rescue Hyperclient::MethodNotAllowedError => e
272
+ e.message # => "DELETE is not allowed on /orders/1, the server allows only GET, HEAD, OPTIONS."
273
+ e.allowed # => ["GET", "HEAD", "OPTIONS"]
274
+ end
275
+ ```
276
+
277
+ Methods are compared case-insensitively, an empty `Allow` header means no methods are allowed, and `HEAD` is only allowed when listed. A resource also exposes the `Allow` header of the response that created it with `_allow` and `_allow?`. Hyperclient never sends extra `OPTIONS` requests.
278
+
279
+ There is no method to clear or override what a link remembers. With `enforce_allowed_methods` on, the remembered `Allow` header is replaced by the link's next response, so call `_options` to ask the server again. Alternatively, use a new link object, which starts without restrictions, such as `link._expand` or a link from a freshly fetched resource.
280
+
212
281
  # Testing Using Hyperclient
213
282
 
214
283
  You can combine RSpec, Faraday::Adapter::Rack and Hyperclient to test your HAL API without having to ever examine the raw JSON response.
@@ -230,13 +299,13 @@ describe Acme::Api do
230
299
  end
231
300
  end
232
301
 
233
- it 'splines returns 3 splines by default' do
234
- expect(client.splines.count).to eq 3
302
+ it 'returns a place' do
303
+ expect(client.places.first.name).to eq 'Balliol College'
235
304
  end
236
305
  end
237
306
  ```
238
307
 
239
- For a complete example refer to [this Splines Demo API test](https://github.com/ruby-grape/grape-with-roar/blob/master/spec/api/splines_endpoint_with_hyperclient_spec.rb).
308
+ For a complete offline example, see the [Oxford demo smoke test](test/oxford_example_test.rb).
240
309
 
241
310
  # Reference
242
311
 
data/RELEASING.md CHANGED
@@ -1,69 +1,58 @@
1
- Releasing Hyperclient
2
- =====================
1
+ # Releasing Hyperclient
3
2
 
4
- There're no particular rules about when to release hyperclient. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
3
+ Release bug fixes frequently, features less frequently, and breaking API changes rarely.
5
4
 
6
- ### Release
5
+ Releases run through the [Release workflow](.github/workflows/release.yml), which uses [ruby-gem-release](https://github.com/dblock/ruby-gem-release/tree/v0.9.0) and RubyGems Trusted Publishing. Merging does not publish anything, and the local Bundler `rake release` task is disabled.
7
6
 
8
- Run tests, check that all tests succeed locally.
7
+ ## One-Time Setup
9
8
 
10
- ```
11
- bundle install
12
- rake
13
- ```
9
+ Create a GitHub environment named `release` in this repository, for example with `gh api --method PUT repos/codegram/hyperclient/environments/release`. To require a maintainer's approval before publication, add required reviewers and restrict deployment to `master`.
14
10
 
15
- Check that the last build succeeded in CI for all supported platforms.
11
+ On RubyGems, open the [hyperclient trusted publishers](https://rubygems.org/gems/hyperclient/trusted_publishers) page and add a GitHub Actions publisher with repository owner `codegram`, repository name `hyperclient`, workflow filename `release.yml`, and environment `release`. Set the separate workflow repository owner to `dblock` and name to `ruby-gem-release`, because publication runs in that reusable workflow. No RubyGems API key is stored.
16
12
 
17
- Increment the version, modify [lib/hyperclient/version.rb](lib/hyperclient/version.rb).
13
+ The workflow needs to push the release commit, the `vVERSION` tag, and the next development commit to `master`. Branch and tag rules must allow that; every release checks them before publishing.
18
14
 
19
- * Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.5.1` to `0.5.2`).
20
- * Increment the second number if the release contains major features or breaking API changes (eg. change `0.5.1` to `0.4.0`).
15
+ ## Prepare the Release
21
16
 
22
- Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
17
+ Releases publish the version in [lib/hyperclient/version.rb](lib/hyperclient/version.rb) with the notes in its `### VERSION (Next)` section of [CHANGELOG.md](CHANGELOG.md). Use a patch version for backward-compatible fixes, a minor version for backward-compatible features, and a major version for breaking changes. To change it, update both files in a pull request, or pass a different version when starting the release.
23
18
 
24
- ```
25
- 0.4.0 (2014-01-27)
26
- ==================
27
- ```
19
+ Check that CI has succeeded on `master`, and don't merge anything while a release is running.
28
20
 
29
- Remove the line with "Your contribution here.", since there will be no more contributions to this release.
21
+ ## Release
30
22
 
31
- Commit your changes.
23
+ Check the setup without releasing anything:
32
24
 
33
- ```
34
- git add CHANGELOG.md lib/hyperclient/version.rb
35
- git commit -m "Preparing for release, 0.4.0."
36
- git push origin master
25
+ ```sh
26
+ gh workflow run release.yml --repo codegram/hyperclient --ref master -f dry-run=true
37
27
  ```
38
28
 
39
- Release.
29
+ Then release the checked-in version:
40
30
 
31
+ ```sh
32
+ gh workflow run release.yml --repo codegram/hyperclient --ref master
41
33
  ```
42
- $ rake release
43
34
 
44
- hyperclient 0.4.0 built to pkg/hyperclient-0.4.0.gem.
45
- Tagged v0.4.0.
46
- Pushed git commits and tags.
47
- Pushed hyperclient 0.4.0 to rubygems.org.
48
- ```
35
+ To release a different version, pass `-f version=2.3.0`.
49
36
 
50
- ### Prepare for the Next Version
37
+ The workflow runs `bundle exec rake` on Ruby 4.0 with [gemfiles/release.gemfile](gemfiles/release.gemfile), dates the changelog section and removes its "Your contribution here." placeholder, publishes the gem to RubyGems, pushes the release commit and tag, and creates a GitHub Release with the changelog notes. It then increments the patch version and pushes a new `### VERSION (Next)` section to `master`.
51
38
 
52
- Add the next release to [CHANGELOG.md](CHANGELOG.md).
39
+ ## Verify and Recover
53
40
 
54
- ```
55
- Next Release
56
- ============
41
+ Check the RubyGems version, the matching tag and GitHub Release, and the next development version on `master`:
57
42
 
58
- * Your contribution here.
43
+ ```sh
44
+ version=2.2.0
45
+ curl --fail --silent --show-error "https://rubygems.org/api/v2/rubygems/hyperclient/versions/$version.json"
46
+ gh release view "v$version" --repo codegram/hyperclient
59
47
  ```
60
48
 
61
- Increment the minor version, modify [lib/hyperclient/version.rb](lib/hyperclient/version.rb).
49
+ Don't rerun a failed release blindly: RubyGems may have accepted the gem. Inspect the existing tag, RubyGems version, and GitHub Release first, and never republish a version or move its tag. Follow the [ruby-gem-release recovery instructions](https://github.com/dblock/ruby-gem-release/blob/v0.9.0/docs/actions/release.md#recovery-artifacts) to complete only the missing steps.
62
50
 
63
- Comit your changes.
51
+ ## Run the Release Tasks Locally
64
52
 
65
- ```
66
- git add CHANGELOG.md lib/hyperclient/version.rb
67
- git commit -m "Preparing for next release, 0.4.1."
68
- git push origin master
53
+ The release tasks need Ruby 3.3+ and the release bundle:
54
+
55
+ ```sh
56
+ BUNDLE_GEMFILE=gemfiles/release.gemfile bundle install
57
+ BUNDLE_GEMFILE=gemfiles/release.gemfile bundle exec rake -T release
69
58
  ```
data/Rakefile CHANGED
@@ -6,6 +6,24 @@ Bundler.setup :default, :test, :development
6
6
 
7
7
  Bundler::GemHelper.install_tasks
8
8
 
9
+ # Releases run through the Release workflow, see RELEASING.md.
10
+ %w[release release:rubygem_push release:source_control_push].each do |name|
11
+ Rake::Task[name].clear
12
+ desc 'Disabled, releases run through the Release workflow (see RELEASING.md)'
13
+ task(name) { abort "#{name} is disabled; releases run through GitHub Actions, see RELEASING.md" }
14
+ end
15
+
16
+ # The release tasks are only installed with BUNDLE_GEMFILE=gemfiles/release.gemfile.
17
+ if Gem.loaded_specs.key?('ruby-gem-release')
18
+ require 'ruby-gem-release/workflow/ruby_gem'
19
+ require 'ruby-gem-release/changelog'
20
+
21
+ RubyGemRelease::Workflow::RubyGem.new(
22
+ version: RubyGemRelease::Version::RubyConstant.new(path: 'lib/hyperclient/version.rb', constant: 'VERSION'),
23
+ changelog: RubyGemRelease::Changelog::Intridea.new(placeholder: '* Your contribution here.')
24
+ ).install_tasks
25
+ end
26
+
9
27
  require 'rake/testtask'
10
28
 
11
29
  Rake::TestTask.new(:test) do |t|
@@ -0,0 +1,42 @@
1
+ # Local Oxford HAL Demo
2
+
3
+ This read-only demo uses a small selection of public place facts from Oxford's retired mobile API. It runs entirely on localhost; neither Oxford nor the Internet Archive is contacted when running the example. The information is historical, not a current directory.
4
+
5
+ From the repository root, install dependencies and start the server:
6
+
7
+ ```sh
8
+ bundle install
9
+ bundle exec ruby examples/oxford/server.rb
10
+ ```
11
+
12
+ In a second terminal:
13
+
14
+ ```sh
15
+ bundle exec ruby -Ilib examples/oxford/client.rb
16
+ ```
17
+
18
+ The server binds only to `127.0.0.1:9292`. Set `PORT` on the server and `OXFORD_URL` on the client to use another port. Stop the server with Ctrl-C.
19
+
20
+ The client demonstrates collection traversal, attributes, a templated place link, following `primary_place`, embedded file metadata, and CURIE expansion. It prints image URLs without downloading images. Unknown paths return 404; writes return 405.
21
+
22
+ ## Provenance and Adaptations
23
+
24
+ The factual fields and original place path in `places.json` were transcribed from [Balliol College's archived response, September 10, 2020](https://web.archive.org/web/20200910141343id_/https://api.m.ox.ac.uk/places/oxpoints:23232339). The record retains the original ID, name, address, coordinates, self/primary-place paths, and one image URL. No image or descriptive prose is redistributed.
25
+
26
+ The [archived API root, July 12, 2024](https://web.archive.org/web/20240712050404id_/http://api.m.ox.ac.uk/) demonstrates the original HAL-style links. See also [Moxie's OxPoints importer documentation](https://moxie.readthedocs.io/en/latest/places/oxpoints.html).
27
+
28
+ ## Data License
29
+
30
+ The underlying OxPoints place data is dedicated to the public domain under [CC0](https://creativecommons.org/publicdomain/zero/1.0/). Oxford's own presentation, [*OxPoints and data.ox.ac.uk*, Alexander Dutton, InfoDev, OUCS (2011)](https://old.ictf.ox.ac.uk/conference/2011/presentations/wks11_oxpoints_dataox.pdf), identifies names, coordinates, addresses, and identifiers as OxPoints data (slides 2-5) and explicitly states "Public domain (CC0; no attribution required)" (slide 8). The place facts in `places.json` come from this dataset via the archived mobile API response cited above; the HAL wrappers and local links are demo adaptations.
31
+
32
+ This is not a license claim for full archived API responses or photographs. The depiction URL is retained only as a reference to an external image; the image itself is not included, fetched, or covered by this notice. Newly authored server code and documentation are under this project's license. Moxie's Apache-2.0 code license is separate from the OxPoints data license.
33
+
34
+ The root, collection wrapper, templated `place` link, `oxford` CURIE, and local relation documentation are demo additions, not a reconstruction of the original service. Responses use `application/hal+json`; the archived service returned `application/json`. Relative place links retain their original paths and resolve locally. Unavailable child links, images, and unrelated API endpoints are not mirrored.
35
+
36
+ ## Tests
37
+
38
+ ```sh
39
+ bundle exec ruby -Itest test/oxford_example_test.rb
40
+ ```
41
+
42
+ The tests exercise the same app and client using local HTTP stubs, without requiring a running server or external network access. They are also included in `bundle exec rake test`.
@@ -0,0 +1,48 @@
1
+ require 'json'
2
+
3
+ module OxfordExample
4
+ # A read-only HAL demo, independent of Oxford's retired API.
5
+ class App
6
+ def initialize
7
+ @places = JSON.parse(File.read(File.join(__dir__, 'places.json')))
8
+ end
9
+
10
+ def call(env)
11
+ return response(405, { 'error' => 'Read-only example' }) unless %w[GET HEAD].include?(env['REQUEST_METHOD'])
12
+
13
+ status, body = representation(env['PATH_INFO'])
14
+ result = response(status, body)
15
+ result[2] = [] if env['REQUEST_METHOD'] == 'HEAD'
16
+ result
17
+ end
18
+
19
+ private
20
+
21
+ def representation(path)
22
+ case path
23
+ when '/'
24
+ [200, {
25
+ '_links' => {
26
+ 'self' => { 'href' => '/' },
27
+ 'places' => { 'href' => '/places/', 'title' => 'Oxford places', 'profile' => '/docs/places' },
28
+ 'place' => { 'href' => '/places/{id}', 'templated' => true },
29
+ 'curies' => [{ 'name' => 'oxford', 'href' => '/docs/{rel}', 'templated' => true }],
30
+ 'oxford:places' => { 'href' => '/places/' }
31
+ }
32
+ }]
33
+ when '/places/'
34
+ [200, { '_links' => { 'self' => { 'href' => '/places/' } },
35
+ '_embedded' => { 'places' => @places } }]
36
+ when '/docs/places'
37
+ [200, { 'description' => 'Archived Oxford place facts in a local HAL collection.' }]
38
+ else
39
+ place = @places.find { |item| item['_links']['self']['href'] == path }
40
+ place ? [200, place] : [404, { 'error' => 'Not included in this example' }]
41
+ end
42
+ end
43
+
44
+ def response(status, body)
45
+ [status, { 'content-type' => 'application/hal+json' }, [JSON.generate(body)]]
46
+ end
47
+ end
48
+ end
@@ -0,0 +1,14 @@
1
+ require 'hyperclient'
2
+
3
+ api = Hyperclient.new(ENV.fetch('OXFORD_URL', 'http://127.0.0.1:9292/'))
4
+ api.places.each do |place|
5
+ puts "#{place.name}: #{place.address}"
6
+ end
7
+
8
+ place = api.place(id: 'oxpoints:23232339')
9
+ puts "Followed primary_place: #{place.primary_place.name}"
10
+ place._embedded.files.each do |file|
11
+ puts "Archived #{file.type} URL (not fetched): #{file.url}"
12
+ end
13
+ puts "CURIE: #{api._links._curies['oxford'].expand('places')}"
14
+ puts "Places profile: #{api._links.places._profile}"
@@ -0,0 +1,21 @@
1
+ [
2
+ {
3
+ "_links": {
4
+ "self": { "href": "/places/oxpoints:23232339" },
5
+ "primary_place": { "href": "/places/oxpoints:23232339" }
6
+ },
7
+ "_embedded": {
8
+ "files": [
9
+ {
10
+ "type": "depiction",
11
+ "url": "//mox-static-files.oucs.ox.ac.uk/oxpoints/23232339/depiction/original/ball.jpg"
12
+ }
13
+ ]
14
+ },
15
+ "id": "oxpoints:23232339",
16
+ "name": "Balliol College",
17
+ "address": "Broad Street OX1 3BJ",
18
+ "lat": "51.754425",
19
+ "lon": "-1.257216"
20
+ }
21
+ ]
@@ -0,0 +1,13 @@
1
+ require 'webrick'
2
+ require_relative 'app'
3
+
4
+ app = OxfordExample::App.new
5
+ server = WEBrick::HTTPServer.new(BindAddress: '127.0.0.1', Port: Integer(ENV.fetch('PORT', '9292')))
6
+ server.mount_proc('/') do |request, response|
7
+ status, headers, body = app.call('REQUEST_METHOD' => request.request_method, 'PATH_INFO' => request.path)
8
+ response.status = status
9
+ headers.each { |key, value| response[key] = value }
10
+ response.body = body.join
11
+ end
12
+ %w[INT TERM].each { |signal| trap(signal) { server.shutdown } }
13
+ server.start
@@ -8,10 +8,11 @@ Spinach.config[:failure_exceptions] << Minitest::Assertion
8
8
 
9
9
  class Spinach::FeatureSteps
10
10
  include Minitest::Assertions
11
+
11
12
  attr_accessor :assertions
12
13
 
13
14
  def initialize(*args)
14
- super(*args)
15
+ super
15
16
  self.assertions = 0
16
17
  end
17
18
  end
@@ -0,0 +1,6 @@
1
+ # Bundle used by the Release workflow, see RELEASING.md.
2
+ # ruby-gem-release requires Ruby 3.3+, so it is kept out of the main Gemfile.
3
+ eval_gemfile '../Gemfile'
4
+
5
+ gem 'commonmarker', '~> 2.10', require: false
6
+ gem 'ruby-gem-release', '0.9.0', require: false
@@ -42,6 +42,7 @@ module Hyperclient
42
42
  @resource = nil
43
43
  @key = nil
44
44
  @uri_variables = nil
45
+ @enforce_allowed_methods = false
45
46
  yield self if block_given?
46
47
  end
47
48
 
@@ -124,6 +125,19 @@ module Hyperclient
124
125
  # value - A Hash containing the client options.
125
126
  attr_accessor :options
126
127
 
128
+ # Public: Set whether links refuse to send a method that the Allow header
129
+ # of their most recent response doesn't list, raising
130
+ # MethodNotAllowedError instead. Defaults to false.
131
+ attr_writer :enforce_allowed_methods
132
+
133
+ # Public: Indicates if links enforce the methods allowed by the Allow
134
+ # header.
135
+ #
136
+ # Returns true if enabled, false otherwise.
137
+ def enforce_allowed_methods?
138
+ @enforce_allowed_methods == true
139
+ end
140
+
127
141
  private
128
142
 
129
143
  # Internal: Returns a block to initialize the Faraday connection. The