jgraichen / restify

Restify is a experimental, parallel and pipelined Hypermedia API client

Restify

Restify is an hypermedia REST client that does parallel, concurrent and keep-alive requests by default.

Restify scans Link headers and returned resource for links and relations to other resources, represented as RFC6570 URI Templates, and exposes those to the developer.

Restify can be used to consume hypermedia REST APIs (like GitHubs), to build a site-specific library or to use within your own backend services.

Restify is build upon the following libraries:

• concurrent-ruby
• addressable
• typhoeus

The HTTP adapters are mostly run in a background thread and may not survive mid-application forks.

Restify includes processors to parse responses and to extract links between resources. The following formats are can be parsed:

• JSON
• MessagePack

Links are extracted from

• HTTP Link header
• Github-style relations in payloads

Planned features

• HTTP cache
• API versions via header
• Content-Type and Language negotiation
• Processors for JSON-HAL, etc.

Installation

Add it to your Gemfile or install it manually: $ gem install restify

Usage

Create new Restify object. It essentially means to request some start-resource usually the "root" resource:

client = Restify.new('https://api.github.com').get.value
# => {"current_user_url"=>"https://api.github.com/user",
#     "current_user_authorizations_html_url"=>"https://github.com/settings/connections/applications{/client_id}",
# ...
#     "repository_url"=>"https://api.github.com/repos/{owner}/{repo}",
# ...

We are essentially requesting 'http://api.github.com' via HTTP get. get is returning an Promise, similar to Java's Future. The value call resolves the returned Promise by blocking the thread until the resource is actually there. value! will additionally raise errors instead of returning nil. You can chain handlers using the then method. This allows you to be build a dependency chain that will be executed when the last promise is needed.

As we can see GitHub returns us a field repository_url with a URI template. Restify automatically scans for *_url fields in the JSON response and exposes these as relations. It additionally scans the HTTP Header field Link for relations like pagination.

We can now use the relations to navigate from resource to resource like a browser from one web page to another page.

repositories = client.rel(:repository)
# => #<Restify::Relation:0x00000005548968 @context=#<Restify::Context:0x007f6024066ae0 @uri=#<Addressable::URI:0x29d8684 URI:https://api.github.com>>, @template=#<Addressable::Template:0x2aa44a0 PATTERN:https://api.github.com/repos/{owner}/{repo}>>

This gets us the relation named repository that we can request now. The usual HTTP methods are available on a relation:

    def get(params = {})
      request :get, nil, params
    end

    def delete(params = {})
      request :delete, nil, params
    end

    def post(data = {}, params = {})
      request :post, data, params
    end

    def put(data = {}, params = {})
      request :put, data, params
    end

    def patch(data = {}, params = {})
      request :patch, data, params
    end

URL templates can define some parameters such as {owner} or {repo}. They will be expanded from the params given to the HTTP method method.

Now send a GET request with some parameters to request a specific repository:

repo = repositories.get(owner: 'jgraichen', repo: 'restify').value

Now fetch a list of commits for this repo and get this first one:

commit = repo.rel(:commits).get.value.first

And print it:

puts "Last commit: #{commit['sha']}"
puts "By #{commit['commit']['author']['name']} <#{commit['commit']['author']['email']}>"
puts "#{commit['commit']['message']}"

See commented example in main spec spec/restify_spec.rb or in the examples directory.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit specs for your feature so that I do not break it later
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create new Pull Request

License

Copyright (C) 2014-2018 Jan Graichen

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.

restify's Issues

Suggestion: Move params attribute to rel

This would obviously be a candidate for an eventual v0.6 release.

I've seen (and experienced) some confusion in regards to the params attribute in the get/post etc. methods.

From the README:

def get(params = {})
def post(data = {}, params = {})

All these methods accept at least one argument, namely the hash of params that will be interpolated / added to the URL when making a request.

For GET requests, this is perfectly straightforward and expected. For e.g. POST requests, it is confusing - which request data belongs where, and why? (Mostly when reading source code, I guess, one can figure it out when writing.)

Since params is actually a part of every request method, I'd suggest to move it to the rel method instead. In fact, I'd argue this even makes sense from a domain perspective: the data passed to params is typically substituted for the placeholders in the relation's URL template, or are optional URL parameters (such as filters).

Thus, when calling rel with some params, the resulting object would not so much be the description of a relation, but rather a handle for a resource in the REST terminology - a relation, bound (identified) to a distinct resource through the params.

Any additional data passed to the various request helper methods would then be sent in the way corresponding to the HTTP method: for GET requests, it would be serialized and appended to the URL, for POST/PUT/DELETE it would be sent as form data / JSON in the request body.

TL;DR Turn this:

repo = client.rel(:repository)
repo = repositories.get(owner: 'jgraichen', repo: 'restify').value

Into this:

client.rel(:repository, owner: 'jgraichen', repo: 'restify').get.value

(One could think about having separate concepts for the generic relation - i.e. the description of a relation with placeholders - and an instantiated relation, i.e. a resource - although that name is already taken...)

What do you think?

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

bundler

Gemfile

• rspec '~> 3.0'

github-actions

.github/workflows/test.yml

• ruby/setup-ruby v1
• ruby/setup-ruby v1
• ubuntu 22.04
• ubuntu 22.04

---

• Check this box to trigger a request for Renovate to run again on this repository

Handling invalid JSON bodies

We encountered this in a test case, where we were using Restify for making requests to our Rails app. This app answered with HTTP 400 for certain invalid parameters. However, Rails sometimes sets the Content-Type header even for requests with empty bodies. This header makes Restify interpret the empty body as JSON, which then raises an exception.

Possible solutions:

• Introduce a special case for empty response bodies, no matter the content type.
• Handle any JSON parsing error and ignore the body - this might be a bit surprising, but it's a possible scenario that needs to be handled somehow. 😕

(Yes, the server is doing something wrong here, but more graceful error handling on the client side would probably be useful, too. At least I am not aware of a protocol for handling processing errors in Restify.)

Missing URI template params can cause wrong URL to be resolved

Example:

Restify.new('http://host/articles/{id}`).get(id: nil).value

This will result in http://host/articles being requested - resulting in errors like:

• unexpected 404s
• exceptions being thrown becasue of treating the returned array as a hash

Even though this usually results in an exception that will sooner or later lead to this realization, maybe unresolvable template parameters like {id} in the example should throw an exception instead?

Add implicit conversion of Restify::Resource into Hash

e.g. for Hash#merge.

[2.0] Change Restify::Processors::Json.indifferent_access default value

Let's change this default value for version 2.0.

This should be more performant and prevent problems with certain attribute names (e.g. Hashie::Mash will complain about count and key).

In addition, we could raise a deprecation warning in the indifferent_access? method when it is accessed for the first time and if it returns true. That way, library users can adopt the new default behavior by calling Restify::Processors::Json.indifferent_access = true somewhere early in their applications.

[2.0] Disallow non-primitive values for query parameters

Right now, we rely on Rails' to_param to pre-serialize values for use in query strings. That means, things like arrays ([1, 2]) are turned into strings separated by slashes ("1/2"). That is very arbitrary and should not be Restify's concern.

Let's disallow these cases (needs a clear definition of what cases are allowed).

This would be a subtle, but impact-ful BC break, so I would propose to target this for 2.0.

Implement __setobj__ for Resource

I discovered an issues when I tried to cache a Restify response, which is encapsulated as a Resource. This is not possible because Resource doesn't implement __setobj__, so as a workaround I had to decapsulate it by getting the data from Resource before. It would be convenient to implement __setobj__ for Resource, also since __getobj__ is already implemented.