Skip to content

Latest commit

 

History

History
149 lines (105 loc) · 6.41 KB

UPGRADING.md

File metadata and controls

149 lines (105 loc) · 6.41 KB
Raw

Upgrading Hyperclient

Upgrading to >= 0.9.0

Previous versions of Hyperclient performed asynchronous requests using futuroscope by default, which could be disabled by providing the :async option to each Hyperclient instance. This has been removed and you can remove any such code.

api = Hyperclient.new('https://grape-with-roar.herokuapp.com/api') do |client|
  client.options[:async] = false
end

The default new behavior is synchronous. We recommend concurrent-ruby for your asynchronous needs.

Include futuroscope in your Gemfile and wrap Hyperclient requests into Futuroscope::Future.new blocks to get the old behavior.

See #133 and #123 for more information.

Upgrading to >= 0.8.0

Changes in curies

Previous versions of Hyperclient misinterpreted the HAL RFC and used curies as if they were designed to enable compact URIs. Curies in HAL are provided for documentation purposes.

Since version 0.8.0 they are no longer expanded. Consider the following example.

{
  "_links": {
    "self": { "href": "/orders" },
    "curies": [{
      "name": "acme",
      "href": "http://docs.acme.com/relations/{rel}",
      "templated": true
    }],
    "acme:widgets": { "href": "/widgets" }
  }
}
client = Hyperclient.new('http://example.org/api')

client._links["acme:widgets"]

# before
# => "http://docs.acme.com/relations/widgets"

# after
# => "http://example.org/api/widgets"

In addition, you can now access and expand the curie.

curie = client._links._curies["acme"]
curie.expand('widgets')
# => "http://docs.acme.com/relations/widgets"

See #97 for more information.

Upgrading to >= 0.7.0

Changes in default headers

The default Content-Type is now application/hal+json and the Accept header includes application/hal+json as well. If your API only accepts application/json as Content-Type, you can override the default headers in the client initialization block as such:

Hyperclient.new('https://api.example.org/') do |client|
  client.headers = { 'Content-Type' => 'application/json', 'Accept' => 'application/json,application/hal+json' }
end

Changes to default headers may impact Hyperclient in test

If you are using Hyperclient to test an API as described in README.md and if the API expects 'application/hal+json' as the content_type for requests, you may need to update how you set up Hyperclient in your specs. As defined in the default_faraday_block method in Hyperclient::EntryPoint, you can specify that you are encoding requests via faraday as :hal_json.

Hyperclient.new('http://example.org/api') do |client|
  client.connection(default: false) do |conn|
    conn.request :hal_json
    conn.response :json
    conn.use Faraday::Adapter::Rack, app
  end
end

instead of:

Hyperclient.new('http://example.org/api') do |client|
  client.connection(default: false) do |conn|
    conn.request :json
    conn.response :json
    conn.use Faraday::Adapter::Rack, app
  end
end

Upgrading to >= 0.6.0

Changes in HTTP Error Handling

The default Faraday block now uses Faraday::Response::RaiseError and will cause HTTP errors to be raised as exceptions. Older versions of Hyperclient swallowed the error and returned an empty resource. If you relied on checking for an HTTP response status, rescue Faraday::ClientError.

Changes in Values Returned from HTTP Methods

The Link#_get method has been aliased to _resource. All HTTP methods, including _post, _put, _delete, _patch, _options and _head now return instances of Resource. Older versions returned a Faraday::Response.

Changes in URI Template Expansion

A MissingURITemplateVariablesException exception will no longer be raised when expanding a link with no arguments. The Link#_expand method will now also accept zero arguments and default the variables to {}. This enables support for templated links with all optional arguments.

Upgrading to >= 0.5.0

Remove Navigational Elements

You can, but no longer need to invoke links, embedded, expand, attributes or resource in most cases. Simply remove them. Navigational structures like key.embedded.key can also be collapsed.

Here're a few examples:

Instead Of Write This
api.links.widgets api.widgets
api.links.widgets.embedded.widgets.first api.widgets.first
api.links.widgets.embedded.comments api.widgets.comments
api.links.widget.expand(id: 3) api.widget(id: 3)
api.links.widget.expand(id: 3).resource.id api.widget(id: 3).id

If you prefer to specify the complete HAL navigational structure, you must rename the methods to their new underscore equivalents. See below.

Change Naviational Elements and HTTP Verbs to Underscore Versions

Navigational methods and HTTP verbs have been renamed to their underscore versions and are otherwise treated as attributes.

Instead Of Write This
api.links api._links
api.links.widgets.embedded.widgets.first api._links.widgets._embedded.first
api.links.widget.expand(id: 3).resource api._links.widget._expand(id: 3)._resource
api.get api._get
api.links.widgets.widget(id: 3).delete api._links.widget._expand(id: 3)._delete
api.links.widgets.post(name: 'a widget') `api._links.widgets._post(name: 'a widget')
api.links.widget.expand(id: 3).put(name: 'updated) api._links.widget._expand(id: 3)._put(name: 'updated')

For more information see #63.