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.
- checksums.yaml +4 -4
- data/.github/workflows/coverage.yml +14 -10
- data/.github/workflows/danger-comment.yml +18 -0
- data/.github/workflows/danger.yml +8 -17
- data/.github/workflows/lint.yml +10 -3
- data/.github/workflows/release.yml +26 -0
- data/.github/workflows/test.yml +21 -5
- data/.gitignore +3 -0
- data/.rubocop.yml +1 -1
- data/.rubocop_todo.yml +8 -5
- data/AGENTS.md +26 -0
- data/CHANGELOG.md +25 -4
- data/CONTRIBUTING.md +10 -0
- data/Dangerfile +2 -0
- data/Gemfile +14 -3
- data/README.md +110 -41
- data/RELEASING.md +32 -43
- data/Rakefile +18 -0
- data/examples/oxford/README.md +42 -0
- data/examples/oxford/app.rb +48 -0
- data/examples/oxford/client.rb +14 -0
- data/examples/oxford/places.json +21 -0
- data/examples/oxford/server.rb +13 -0
- data/features/support/env.rb +2 -1
- data/gemfiles/release.gemfile +6 -0
- data/lib/hyperclient/entry_point.rb +14 -0
- data/lib/hyperclient/link.rb +133 -8
- data/lib/hyperclient/resource.rb +27 -0
- data/lib/hyperclient/version.rb +1 -1
- data/test/hyperclient/attributes_test.rb +9 -0
- data/test/hyperclient/collection_test.rb +22 -0
- data/test/hyperclient/curie_test.rb +7 -0
- data/test/hyperclient/entry_point_test.rb +36 -0
- data/test/hyperclient/link_collection_test.rb +10 -0
- data/test/hyperclient/link_test.rb +434 -1
- data/test/hyperclient/resource_test.rb +65 -1
- data/test/hyperclient_test.rb +1 -0
- data/test/oxford_example_test.rb +63 -0
- data/test/test_helper.rb +1 -2
- metadata +13 -8
- data/.DS_Store +0 -0
- data/examples/splines_api.rb +0 -39
data/README.md
CHANGED
|
@@ -2,8 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](http://badge.fury.io/rb/hyperclient)
|
|
4
4
|
[](https://github.com/codegram/hyperclient/actions/workflows/test.yml)
|
|
5
|
-
[](https://coveralls.io/r/codegram/hyperclient?branch=master)
|
|
5
|
+
[](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 [
|
|
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('
|
|
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('
|
|
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('
|
|
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('
|
|
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('
|
|
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('
|
|
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('
|
|
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('
|
|
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.
|
|
116
|
-
puts "
|
|
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.
|
|
124
|
-
puts "A
|
|
125
|
-
puts "
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
|
|
143
|
-
puts
|
|
154
|
+
place = api.place(id: 'oxpoints:23232339')
|
|
155
|
+
puts place.name # => Balliol College
|
|
144
156
|
```
|
|
145
157
|
|
|
146
|
-
Invoking `api.
|
|
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
|
|
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
|
|
156
|
-
puts
|
|
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
|
|
204
|
+
puts place.to_h['name'] # => Balliol College
|
|
165
205
|
```
|
|
166
206
|
|
|
167
|
-
|
|
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
|
-
|
|
184
|
-
|
|
185
|
-
spline._options
|
|
223
|
+
place = api.place(id: 'oxpoints:23232339')
|
|
224
|
+
place._head
|
|
186
225
|
```
|
|
187
226
|
|
|
188
|
-
|
|
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
|
-
|
|
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
|
-
|
|
199
|
-
|
|
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
|
-
|
|
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 '
|
|
234
|
-
expect(client.
|
|
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
|
|
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
|
-
|
|
3
|
+
Release bug fixes frequently, features less frequently, and breaking API changes rarely.
|
|
5
4
|
|
|
6
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
21
|
+
## Release
|
|
30
22
|
|
|
31
|
-
|
|
23
|
+
Check the setup without releasing anything:
|
|
32
24
|
|
|
33
|
-
```
|
|
34
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
51
|
+
## Run the Release Tasks Locally
|
|
64
52
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
data/features/support/env.rb
CHANGED
|
@@ -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
|