<commit_before># Excon::Hypermedia

Teaches [Excon][] how to talk to [HyperMedia APIs][hypermedia].

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'excon-hypermedia'
```

And then execute:

```shell
bundle
```

Or install it yourself as:

```shell
gem install excon-hypermedia
```

## Usage

**NOTE**: This library is in very early development. Right now, it only talks
the `HAL/JSON` protocol, and it only knows how to follow (non-curie) link
relations. It returns raw response bodies in string format.

This gem adds a thin layer on top of [Excon][excon] to make it talk with an
HyperMedia-enabled API. To let Excon know the connection supports HyperMedia,
simply add the `hypermedia: true` option.

```ruby
conn = Excon.new('http://www.example.com/api.json', hypermedia: true)
conn.class # => Excon::Connection
```

From that point on, you can use this single connection to make all requests. The
`hypermedia` option will be passed on to all subsequent connection objects, as
long as you keep chaining the requests from the original top-level connection.

```ruby
product = conn.product(expand: { uid: 'hello' })
product.class # => Excon::Connection

response = product.get
response.class # => Excon::Response
response.body.class # => String
```

As seen above, you can expand URI Template variables using the `expand` option,
provided by the [`excon-addressable` library][excon-addressable].

You can mark any connection object as hypermedia-aware – not just the top-level
entrypoint – by passing in the `hypermedia: true` option:

```ruby
user = Excon.new('http://www.example.com/users/jeanmertz', hypermedia: true)
user.orders.class # => Excon::Connection
```

Since each new resource is simply an `Excon::Connection` object, all
[Excon-provided options][options] are available as well:

```ruby
product.get(idempotent: true, retry_limit: 6)
```

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

## TODO

* use Excon's Middleware system
* make it easy to access attributes in response objects
* properly handle curied-links and/or non-valid Ruby method name links
* work correctly with Excon.get/post/delete shortcut methods

[excon]: https://github.com/excon/excon
[hypermedia]: https://en.wikipedia.org/wiki/HATEOAS
[excon-addressable]: https://github.com/JeanMertz/excon-addressable
[options]: https://github.com/excon/excon#options<commit_msg>update README to describe new Middleware setup<commit_after># Excon::Hypermedia

Teaches [Excon][] how to talk to [HyperMedia APIs][hypermedia].

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'excon-hypermedia'
```

And then execute:

```shell
bundle
```

Or install it yourself as:

```shell
gem install excon-hypermedia
```

## Usage

**NOTE**: This library is in very early development. Right now, it only talks
the `HAL/JSON` protocol, and it only knows how to follow (non-curie) link
relations. It returns raw response bodies in string format.

This gem adds a thin layer on top of [Excon][excon] to make it talk with an
HyperMedia-enabled API. To let Excon know the connection supports HyperMedia,
simply enable the correct middleware (either globally, or per-connection):

```ruby
Excon.defaults[:middlewares].push(Excon::HyperMedia::Middleware)

api = Excon.get('http://www.example.com/api.json')
api.class # => Excon::Response
```

Using the `HyperMedia` middleware, the `Excon::Response` object now knows how
to handle the HyperMedia aspect of the API:

```ruby
product = api.product(expand: { uid: 'hello' })
product.class # => Excon::Connection

response = product.get
response.class # => Excon::Response
response.body.class # => String
```

As seen above, you can expand URI Template variables using the `expand` option,
provided by the [`excon-addressable` library][excon-addressable].

Since each new resource is simply an `Excon::Response` object, accessed through
the default `Excon::Connection` object, all [Excon-provided options][options]
are available as well:

```ruby
product.get(idempotent: true, retry_limit: 6)
```

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

## TODO

* make it easy to access attributes in response objects
* properly handle curied-links and/or non-valid Ruby method name links

[excon]: https://github.com/excon/excon
[hypermedia]: https://en.wikipedia.org/wiki/HATEOAS
[excon-addressable]: https://github.com/JeanMertz/excon-addressable
[options]: https://github.com/excon/excon#options
{'fraction_non_alphanumeric': 0.11575282854656223, 'fraction_numerical': 0.0004351610095735422, 'mean_word_length': 5.024901703800786, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 12, 'https://': 8, 'lorem ipsum': 0, 'www.': 3, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1903364', 'n_tokens_mistral': 1410, 'n_tokens_neox': 1339, 'n_words': 515}