Roar Got Better Http Support!

Morning everyone! The latest “Roar 0.12.3”: release comes along with some long-awaited features and I wonder why it took me so long.

I added some functionality to the client layer of Roar. As you might recall, Roar allows representers to be used both for backends and on the client side.

h3. Roar’s Client Layer

Let’s run quickly through how to build a REST client with Roar.

As always, we need a representer to specify the exchanged document.

module SongRepresenter
  include Roar::Representer::JSON

  property :title

Next, I write a simple client class that consumes from the existing PunkrockAPI™. Please excuse my use of @OpenStruct@, but I’m lazy. And… aren’t lazy programmers the better programmers?

class Song < OpenStruct
  include Roar::Representer::JSON
  include SongRepresenter
  include Roar::Representer::Feature::HttpVerbs

We’ll discuss what happens here in a second.

h3. Simpler HTTP API.

Here’s how you use that client, first.

song =
song.get(uri: "http://songs/roxanne", 
          as: "application/json")

song.title #=> "Roxanne"

The @HttpVerbs@ module adds verbs to the client model. In this example, I use @#get@ to retrieve the document from the specified URL, parse it and assign properties to the object. Since we also mixed in @SongRepresenter@, the client knows about the document’s structure and the attributes.

Note the *new API for @#get@, @#post@, etc.* You now use keys to specify arguments, no positional arguments anymore. No need to panic, we added a soft transition with deprecations.

h3. HTTPS Support!

Let’s assume the PunkrockAPI™ goes SSL, requiring your client to use a HTTPS connection. This was a pain so far, check out how it works now.

song.get(uri: "https://songs/roxanne", 
          as: "application/json")

Exactly – you don’t have to do anything besides specifying @https://@ as the protocol, Roar does the “REST” for you.

h3. Basic Authentication

To make it even harder, the API wants you to authenticate beforehand. Basic auth was a feature missing for a long time in Roar. Here it comes.

song.get(       uri: "https://songs/roxanne", 
                 as: "application/json",
         basic_auth: ["nick", "secret password"])

Pass in necessary credentials with the @basic_auth:@ option. Done.

h3. Configuring The Request.

The verbs now allow you to mess around with the @Request@ object, too. It is yielded to the block before the request is sent.

song.get(...) do |req|
  req.add_field("Cookie", "Yummy")

Couldn’t be simpler to create a cookie, change the @Accept:@ header or whatever. The yielded object is a request instance from the @NetHTTP@ implementation (unless you’re using Faraday).

h3. Too High-Level!

Sometimes the verbs might be too high-level, too smart, doing to much. You’re free to use the underlying “@Transport@ methods”: instead. They just do a raw HTTP request.

res = song.http.get_uri(uri: "http://songs/roxanne")
res.body #=> '{"title": "Roxanne"}'

h3. More Soon!

These minor additions have helped a lot in my current project to communicate with the Auspost API. Stay tuned for a major update of Roar. We’re planning better defaults, full Faraday support, simpler nesting, and more.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s