hyperclient 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '02694a72cb9a16a0faac55b463c859a470bce22f7976b0b77c19da138cceded8'
-  data.tar.gz: d96697a7e493f29b2a3207850b961664cfa18e0195b526abb16c9c108b2e2bc3
+  metadata.gz: f6f97641ae8ac6b8ee5e917bb42885454ccfa4dfbe29f91fbe488266c3d8df1b
+  data.tar.gz: 1b4da773e4b20cb6e4ba0e4acec481d586b9101d1cbc6010e0072b9366e7e495
 SHA512:
-  metadata.gz: 45bb98cc9a22fd721c71f32a4e7b2634610279fe66a8466d6f2339efb994853896ed33867baa3e460cd805055b2b2611108d703f7c7788b952ef3693393140fd
-  data.tar.gz: c3c47fee4c97362f31c40a8923eec8c7573be28e215a43bdaac89c44e573cd93cec57291932718dd1bd136689c9f46f1ceff2ace244d613d76871cf9e7529df6
+  metadata.gz: 9786c186df822fa748372f4ad8591f949f53ea37625e78946da83e16572bec228e59c0cbfea2bb5f287c6b81f513e2a7b3c46ce98a7c0f8d48dc6ca88d4792ef
+  data.tar.gz: 8a525a635faa47057352eb5bfb8cde4d65a3d81fd41e9a2c536bc465170249fa0dc8f84d00f8f7e865bb849a076160ce6ec9dc02ba8ac637c2dbc88a8c399e72

data/.github/workflows/coverage.yml

@@ -10,15 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-    - name: Install Ruby (2.7)
-      uses: ruby/setup-ruby@v1
+    - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.7
+        ruby-version: '4.0'
         bundler-cache: true
-    - name: Build and test with RSpec
-      run: |
-        bundle exec rake test
-    - name: Coveralls
-      uses: coverallsapp/github-action@master
+    - run: |
+        bundle exec rake test spinach
+    - uses: coverallsapp/github-action@v2
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/danger-comment.yml

@@ -0,0 +1,11 @@
+name: Danger Comment
+
+on:
+  workflow_run:
+    workflows: [Danger]
+    types: [completed]
+
+jobs:
+  comment:
+    uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0
+    secrets: inherit

data/.github/workflows/danger.yml

@@ -1,22 +1,13 @@
----
-name: danger
+name: Danger
+
 on:
   pull_request:
     types: [opened, reopened, edited, synchronize]
+
 jobs:
   danger:
-    runs-on: ubuntu-20.04
-    steps:
-    - uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 2.7
-        bundler-cache: true
-    - name: Run Danger
-      run: |
-        # the personal token is public, this is ok, base64 encode to avoid tripping Github
-        TOKEN=$(echo -n Z2hwX0xNQ3VmanBFeTBvYkZVTWh6NVNqVFFBOEUxU25abzBqRUVuaAo= | base64 --decode)
-        DANGER_GITHUB_API_TOKEN=$TOKEN bundle exec danger --verbose
+    uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0
+    secrets: inherit
+    with:
+      ruby-version: '4.0'
+      bundler-cache: true

data/.github/workflows/lint.yml

@@ -10,7 +10,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '2.7'
+          ruby-version: '4.0'
           bundler-cache: true
       - run: bundle exec rubocop
 

data/.github/workflows/test.yml

@@ -8,11 +8,16 @@ jobs:
       fail-fast: false
       matrix:
         entry:
+          - { ruby: '4.0' }
+          - { ruby: '3.4' }
+          - { ruby: '3.2', json: '2' }
           - { ruby: '3.2' }
-          - { ruby: '2.7' }
+          - { ruby: '2.7', json: '2' }
           - { ruby: 'ruby-head', allowed-failure: true }
           - { ruby: 'jruby-head', allowed-failure: true }
-    name: test (${{ matrix.entry.ruby }})
+    name: test (Ruby ${{ matrix.entry.ruby }}, JSON ${{ matrix.entry.json || '3' }})
+    env:
+      JSON_VERSION: ${{ matrix.entry.json || '3' }}
     steps:
       - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1

data/.gitignore

@@ -1,4 +1,5 @@
 *.gem
+.DS_Store
 *.rbc
 .bundle
 .config

data/.rubocop.yml

@@ -1,6 +1,6 @@
 inherit_from: .rubocop_todo.yml
 
-require:
+plugins:
   - rubocop-rake
   - rubocop-minitest
 

data/.rubocop_todo.yml

@@ -1,14 +1,13 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-02-01 15:28:54 UTC using RuboCop version 1.48.1.
+# on 2025-09-10 13:55:47 UTC using RuboCop version 1.80.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
 # Offense count: 1
-# Configuration parameters: Severity, Include.
-# Include: **/*.gemspec
+# Configuration parameters: Severity.
 Gemspec/RequiredRubyVersion:
   Exclude:
     - 'hyperclient.gemspec'
@@ -20,6 +19,7 @@ Lint/EmptyBlock:
     - 'test/hyperclient/entry_point_test.rb'
 
 # Offense count: 4
+# Configuration parameters: AllowedParentClasses.
 Lint/MissingSuper:
   Exclude:
     - 'lib/hyperclient/attributes.rb'
@@ -29,16 +29,19 @@ Lint/MissingSuper:
 
 # Offense count: 1
 # This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: AllowedMethods.
+# Configuration parameters: AllowedMethods, InferNonNilReceiver, AdditionalNilMethods.
 # AllowedMethods: instance_of?, kind_of?, is_a?, eql?, respond_to?, equal?
+# AdditionalNilMethods: present?, blank?, try, try!
 Lint/RedundantSafeNavigation:
   Exclude:
     - 'lib/hyperclient/link.rb'
 
 # Offense count: 3
 # This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle.
+# Configuration parameters: EnforcedStyle, EnforcedStyleForClasses, EnforcedStyleForModules.
 # SupportedStyles: nested, compact
+# SupportedStylesForClasses: ~, nested, compact
+# SupportedStylesForModules: ~, nested, compact
 Style/ClassAndModuleChildren:
   Exclude:
     - 'features/steps/api_navigation.rb'

data/AGENTS.md

@@ -0,0 +1,26 @@
+# Agent Guide
+
+Hyperclient is a Ruby client for JSON HAL APIs, built on Faraday 2 and `faraday_hal_middleware`.
+
+## Layout
+
+- `lib/hyperclient.rb`: client entry point and configuration.
+- `lib/hyperclient/`: resources, links, collections, attributes, and CURIEs.
+- `test/`: Minitest tests and fixtures.
+- `features/`: Spinach acceptance tests and supporting code.
+- `examples/`: runnable usage examples.
+
+## Commands
+
+```sh
+bundle install
+bundle exec rake                 # Minitest, Spinach, and RuboCop
+bundle exec rake test            # Minitest only
+bundle exec rake spinach         # Acceptance tests only
+bundle exec rake rubocop         # Lint
+bundle exec ruby -Itest test/hyperclient_test.rb
+```
+
+## Changes
+
+Follow existing Ruby conventions and preserve Ruby 2.7 compatibility. Add regression tests for behavior changes; use existing HTTP stubs rather than depending on external services. Update the README for public API changes and the changelog with the pull request number. See `CONTRIBUTING.md` for the full contribution workflow and `.github/workflows/` for the CI matrix.

data/CHANGELOG.md

@@ -1,10 +1,20 @@
 ## Changelog
 
+### 2.1.0 (2026/10/14)
+
+* [#328](https://github.com/codegram/hyperclient/pull/328): Replaced the retired Splines demo with a local read-only Oxford HAL example using archived place facts - [@dblock](https://github.com/dblock).
+* [#298](https://github.com/codegram/hyperclient/pull/300): Upgraded RuboCop to 1.80.2 - [@dblock](https://github.com/dblock).
+* [#298](https://github.com/codegram/hyperclient/pull/298): Upgraded RuboCop to 1.63.5 - [@dblock](https://github.com/dblock).
+* [#319](https://github.com/codegram/hyperclient/pull/319): Fixed `Resource#to_h` returning `nil` instead of the same result as `#to_hash` - [@dblock](https://github.com/dblock).
+* [#320](https://github.com/codegram/hyperclient/pull/320): Documented how to handle non-`hal+json` responses via the Faraday response middleware's `content_type` matcher - [@dblock](https://github.com/dblock).
+* [#321](https://github.com/codegram/hyperclient/pull/321): Added Ruby 4.0 to the CI test matrix - [@dblock](https://github.com/dblock).
+* [#322](https://github.com/codegram/hyperclient/pull/322): Fixed `Link` caching a mutating request's (`_post`/`_put`/`_patch`/`_delete`) response as its resource, causing subsequent reads (e.g. `#each`, `method_missing`) to return stale data instead of a fresh `_get` - [@dblock](https://github.com/dblock).
+* [#325](https://github.com/codegram/hyperclient/pull/325): Added JSON 2.x/3.x to the CI matrix and JSON response parsing regression tests, retaining Ruby 2.7 coverage with JSON 2.x; upgraded RuboCop to 1.91.0 to allow JSON 3.x - [@dblock](https://github.com/dblock).
 ### 2.0.0 (2024/02/01)
 
 * [#268](https://github.com/codegram/hyperclient/pull/268): Replace Travis-CI with GHA - [@dblock](https://github.com/dblock).
 * [#269](https://github.com/codegram/hyperclient/pull/269): Re-add code coverage - [@dblock](https://github.com/dblock).
-* [#270](https://github.com/codegram/hyperclient/pull/270): Upgrade Rubocop to 1.45 - [@dblock](https://github.com/dblock).
+* [#270](https://github.com/codegram/hyperclient/pull/270): Upgrade RuboCop to 1.45 - [@dblock](https://github.com/dblock).
 * [#271](https://github.com/codegram/hyperclient/pull/271): Test against Ruby 3.2 - [@dblock](https://github.com/dblock).
 * [#285](https://github.com/codegram/hyperclient/pull/285): Support Faraday 2.x - [@dblock](https://github.com/dblock).
 
@@ -39,14 +49,14 @@
 ### 0.9.0 (2018/01/10)
 
 * [#133](https://github.com/codegram/hyperclient/pull/133): Removed futuroscope - [@dblock](https://github.com/dblock).
-* [#131](https://github.com/codegram/hyperclient/pull/131): Upgrade to Rubocop 0.50.0, fix Bundler's insecure git source warning - [@nebolsin](https://github.com/nebolsin).
+* [#131](https://github.com/codegram/hyperclient/pull/131): Upgrade to RuboCop 0.50.0, fix Bundler's insecure git source warning - [@nebolsin](https://github.com/nebolsin).
 * [#132](https://github.com/codegram/hyperclient/pull/132): Swapped yard dependency for danger-toc - [@dblock](https://github.com/dblock).
 
 ### 0.8.6 (2017/08/27)
 
 * [#122](https://github.com/codegram/hyperclient/pull/122): Improve error message when server returns invalid data - [@ivoanjo](https://github.com/ivoanjo).
 * [#125](https://github.com/codegram/hyperclient/pull/125): Add table of contents to readme and add note asking users to add their projects to the wiki - [@ivoanjo](https://github.com/ivoanjo).
-* [#127](https://github.com/codegram/hyperclient/pull/127): Minor fixes: Fix warnings, and pry-byebug to dev Gemfile and tweak rubocop execution - [@ivoanjo](https://github.com/ivoanjo).
+* [#127](https://github.com/codegram/hyperclient/pull/127): Minor fixes: Fix warnings, and pry-byebug to dev Gemfile and tweak RuboCop execution - [@ivoanjo](https://github.com/ivoanjo).
 * [#128](https://github.com/codegram/hyperclient/pull/128): Fix link delegation returning nil for field with value false - [@ivoanjo](https://github.com/ivoanjo).
 
 ### 0.8.5 (2017/07/05)
@@ -107,7 +117,7 @@
 * [#64](https://github.com/codegram/hyperclient/issues/64): Added support for curies - [@dblock](https://github.com/dblock).
 * [#58](https://github.com/codegram/hyperclient/issues/58): Automatically follow redirects - [@dblock](https://github.com/dblock).
 * [#63](https://github.com/codegram/hyperclient/pull/63): You can omit the navigational elements, `api.links.products` is now equivalent to `api.products` - [@dblock](https://github.com/dblock).
-* [#61](https://github.com/codegram/hyperclient/pull/61): Implemented Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
+* [#61](https://github.com/codegram/hyperclient/pull/61): Implemented RuboCop, Ruby-style linter - [@dblock](https://github.com/dblock).
 
 ### 0.4.0 (2014/05/05)
 

data/CONTRIBUTING.md

@@ -32,6 +32,16 @@ bundle install
 bundle exec rake
 ```
 
+CI runs the test suites with JSON 2.x on Ruby 2.7, both JSON 2.x and 3.x on Ruby 3.2, and JSON 3.x on Ruby 3.4, Ruby 4.0, and the head builds.
+To select a JSON major version locally, resolve the bundle and run the tests with the same `JSON_VERSION`:
+
+```
+JSON_VERSION=2 bundle update json
+JSON_VERSION=2 bundle exec rake test spinach
+JSON_VERSION=3 bundle update json
+JSON_VERSION=3 bundle exec rake test spinach
+```
+
 #### Write Tests
 
 Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [test/hyperclient](test/hyperclient).

data/Dangerfile

@@ -1,2 +1,4 @@
+danger.import_dangerfile(gem: 'danger-pr-comment')
+
 changelog.check!
 toc.check!

data/Gemfile

@@ -2,6 +2,8 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'json', "~> #{ENV['JSON_VERSION']}.0" if ENV['JSON_VERSION']
+
 group :development do
   gem 'growl'
   gem 'guard'
@@ -13,15 +15,18 @@ end
 
 group :development, :test do
   gem 'rake'
-  gem 'rubocop', '~> 1.48.0', require: false
+  gem 'rubocop', '~> 1.92.0', require: false
   gem 'rubocop-minitest', require: false
   gem 'rubocop-rake', require: false
   gem 'simplecov', require: false
   gem 'simplecov-lcov', require: false
+  gem 'webrick', '~> 1.8'
 end
 
 group :test do
-  gem 'danger-changelog', '~> 0.6.0'
+  gem 'danger', '~> 9.5'
+  gem 'danger-changelog', '~> 0.8.0'
+  gem 'danger-pr-comment', '~> 0.1.0'
   gem 'danger-toc', '~> 0.2.0'
   gem 'minitest'
   gem 'mocha'

data/README.md

@@ -2,8 +2,7 @@
 
 [![Gem Version](http://img.shields.io/gem/v/hyperclient.svg)](http://badge.fury.io/rb/hyperclient)
 [![Build Status](https://github.com/codegram/hyperclient/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/codegram/hyperclient/actions/workflows/test.yml)
-[![Code Climate](https://codeclimate.com/github/codegram/hyperclient.svg)](https://codeclimate.com/github/codegram/hyperclient)
-[![Coverage Status](https://img.shields.io/coveralls/codegram/hyperclient.svg)](https://coveralls.io/r/codegram/hyperclient?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/codegram/hyperclient/badge.svg?branch=master)](https://coveralls.io/github/codegram/hyperclient?branch=master)
 
 Hyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON HAL](http://stateless.co/hal_specification.html).
 
@@ -25,7 +24,9 @@ Hyperclient is a Hypermedia API client written in Ruby. It fully supports [JSON
 
 # Usage
 
-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).
+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).
+
+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+).
 
 ## API Client
 
@@ -34,13 +35,13 @@ Create an API client.
 ```ruby
 require 'hyperclient'
 
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')
+api = Hyperclient.new('http://127.0.0.1:9292/')
 ```
 
 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.
 
 ```ruby
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
+api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
   client.headers['Access-Token'] = 'token'
 end
 ```
@@ -48,7 +49,7 @@ end
 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.
 
 ```ruby
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
+api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
   client.connection do |conn|
     conn.use Faraday::Request::Instrumentation
   end
@@ -58,7 +59,7 @@ end
 You can pass options to the Faraday connection block in the `connection` block:
 
 ```ruby
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
+api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
   client.connection(ssl: { verify: false }) do |conn|
     conn.use Faraday::Request::Instrumentation
   end
@@ -68,7 +69,7 @@ end
 Or when using the default connection configuration you can use `faraday_options`:
 
 ```ruby
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
+api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
   client.faraday_options = { ssl: { verify: false } }
 end
 ```
@@ -76,7 +77,7 @@ end
 You can build a new Faraday connection block without inheriting default middleware by specifying `default: false` in the `connection` block.
 
 ```ruby
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
+api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
   client.connection(default: false) do |conn|
     conn.request :json
     conn.response :json, content_type: /\bjson$/
@@ -85,12 +86,14 @@ api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
 end
 ```
 
+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`.
+
 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.
 
 ```ruby
 require 'faraday/digestauth'
 
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
+api = Hyperclient.new('http://127.0.0.1:9292/') do |client|
   client.connection(default: false) do |conn|
     conn.request :digest, 'username', 'password'
     conn.request :json
@@ -103,7 +106,7 @@ end
 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).
 
 ```ruby
-api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api')
+api = Hyperclient.new('http://127.0.0.1:9292/')
 api.connection.use :http_cache
 ```
 
@@ -112,48 +115,54 @@ api.connection.use :http_cache
 Hyperclient will fetch and discover the resources from your API and automatically paginate when possible.
 
 ```ruby
-api.splines.each do |spline|
-  puts "A spline with ID #{spline.uuid}."
+api.places.each do |place|
+  puts "#{place.name} has ID #{place.id}."
 end
 ```
 
 Other methods, including `[]` and `fetch` are also available
 
 ```ruby
-api.splines.each do |spline|
-  puts "A spline with ID #{spline[:uuid]}."
-  puts "Maybe with reticulated: #{spline.fetch(:reticulated, '-- no reticulated')}"
+api.places.each do |place|
+  puts "A place with ID #{place[:id]}."
+  puts "Address: #{place.fetch(:address, '-- no address')}"
 end
 ```
 
 ## Links and Embedded Resources
 
-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`.
+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:
 
 ```ruby
-api._links.splines
+api._links.places._embedded.places.each do |place|
+  puts place.name
+end
+
+place = api.place(id: 'oxpoints:23232339')
+puts place.primary_place.name # follows a relative link to Balliol College
+puts place._embedded.files.first.url # reads embedded metadata, without fetching the image
 ```
 
 ## Templated Links
 
-Templated links require variables to be expanded. For example, the demo API has a link called "spline" that requires a spline "uuid".
+Templated links require variables to be expanded. The local demo adds a `place` link that accepts an Oxford place ID.
 
 ```ruby
-spline = api.spline(uuid: 'uuid')
-puts "Spline #{spline.uuid} is #{spline.reticulated ? 'reticulated' : 'not reticulated'}."
+place = api.place(id: 'oxpoints:23232339')
+puts place.name # => Balliol College
 ```
 
-Invoking `api.spline(uuid: 'uuid').reticulated` is equivalent to `api._links.spline._expand(uuid: 'uuid')._resource._attributes.reticulated`.
+Invoking `api.place(id: 'oxpoints:23232339').name` is equivalent to `api._links.place._expand(id: 'oxpoints:23232339')._resource._attributes.name`.
 
 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`.
 
 ## Curies
 
-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.
+Curies provide compact names for relation documentation. The local demo adds an `oxford` CURIE and an `oxford:places` relation.
 
 ```ruby
-puts spline['image:thumbnail'] # => https://grape-with-roar.herokuapp.com/api/splines/uuid/images/thumbnail.jpg
-puts spline.links._curies['image'].expand('thumbnail') # => /docs/images/thumbnail
+puts api._links['oxford:places']._embedded.places.first.name # => Balliol College
+puts api._links._curies['oxford'].expand('places') # => /docs/places
 ```
 
 ## Attributes
@@ -161,10 +170,10 @@ puts spline.links._curies['image'].expand('thumbnail') # => /docs/images/thumbna
 Resource attributes can also be accessed as a hash.
 
 ```ruby
-puts spline.to_h # => {"uuid" => "uuid", "reticulated" => true}
+puts place.to_h['name'] # => Balliol College
 ```
 
-The above is equivalent to `spline._attributes.to_h`.
+`place.to_h` is equivalent to `place._attributes.to_h`.
 
 ## HTTP
 
@@ -180,31 +189,27 @@ api._response.body
 Other methods, including `_head` or `_options` are also available.
 
 ```ruby
-spline = api.spline(uuid: 'uuid')
-spline._head
-spline._options
+place = api.place(id: 'oxpoints:23232339')
+place._head
 ```
 
-Invoke `_post` to create resources.
+The Oxford demo is read-only and rejects writes with HTTP 405. On a writable API, invoke `_post` to create resources:
 
 ```ruby
-splines = api.splines
-splines._post(uuid: 'new uuid', reticulated: false)
+api.places._post(name: 'New place')
 ```
 
 Invoke `_put` or `_patch` to update resources.
 
 ```ruby
-spline = api.spline(uuid: 'uuid')
-spline._put(reticulated: true)
-spline._patch(reticulated: true)
+place._put(name: 'Updated place')
+place._patch(name: 'Updated place')
 ```
 
 Invoke `_delete` to destroy a resource.
 
 ```
-spline = api.spline(uuid: 'uuid')
-spline._delete
+place._delete
 ```
 
 HTTP methods always return a new instance of Resource.
@@ -230,13 +235,13 @@ describe Acme::Api do
     end
   end
 
-  it 'splines returns 3 splines by default' do
-    expect(client.splines.count).to eq 3
+  it 'returns a place' do
+    expect(client.places.first.name).to eq 'Balliol College'
   end
 end
 ```
 
-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).
+For a complete offline example, see the [Oxford demo smoke test](test/oxford_example_test.rb).
 
 # Reference