{{{
Morning everyone! The latest “Roar 0.12.3”:https://github.com/apotonick/roar 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 end
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 end
We’ll discuss what happens here in a second.
h3. Simpler HTTP API.
Here’s how you use that client, first.
song = Song.new
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")
end
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”:https://github.com/apotonick/roar/blob/6c64198e5daf35e1ff13f72c58787fd79577c53d/lib/roar/representer/transport/net_http.rb#L71 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.
}}}
Nick Sutterer 