UPGRADING.md
Upgrading Hyperclient
=====================
### Upgrading to >= 0.9.0
Previous versions of Hyperclient performed asynchronous requests using [futuroscope](https://github.com/codegram/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.
```ruby
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](https://github.com/ruby-concurrency/concurrent-ruby) for your asynchronous needs.
Include [futuroscope](https://github.com/codegram/futuroscope) in your `Gemfile` and wrap Hyperclient requests into `Futuroscope::Future.new` blocks to get the old behavior.
See [#133](https://github.com/codegram/hyperclient/pull/133) and [#123](https://github.com/codegram/hyperclient/issues/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.
```json
{
"_links": {
"self": { "href": "/orders" },
"curies": [{
"name": "acme",
"href": "http://docs.acme.com/relations/{rel}",
"templated": true
}],
"acme:widgets": { "href": "/widgets" }
}
}
```
```rb
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.
```rb
curie = client._links._curies["acme"]
curie.expand('widgets')
# => "http://docs.acme.com/relations/widgets"
```
See [#97](https://github.com/codegram/hyperclient/issues/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:
```rb
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](https://github.com/codegram/hyperclient#testing-using-hyperclient) 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```](https://github.com/codegram/hyperclient/blob/9f908854395523b38e0d4fc834d6db1f8b6dfb22/lib/hyperclient/entry_point.rb#L129), you can specify that you are encoding requests via faraday as ```:hal_json```.
```ruby
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:
```ruby
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](https://github.com/codegram/hyperclient/pull/63).