Posted by Piotr Solnica on April 29, 2019 under

Today we have another exciting release for you - rom-http 0.8.0 . This is the biggest release of this adapter so far, as it's been integrated fully with the core APIs. This means you can now use rom-http to build HTTP client libraries, and leverage powerful auto-mapping capabilities of rom-rb.

This adapter works in the same way as any other rom-rb adapter. You configure a gateway, register relations with schemas and voilà - you can talk to remote HTTP APIs now. Let's see how this looks in actual code.

GitHub API Example

To connect to a remote HTTP API you simply provide the uri and which response/request handlers should be used, in this case we will set :json :

config = ROM :: Configuration . new ( :http , uri: "https://api.github.com" , handlers: :json )

Now we can define a relation class. For the purpose of this example we'll use a relation that will query /orgs end-point:

module GitHub module Resources class Organizations < ROM :: Relations [ :http ] schema ( :orgs ) do attribute :id , Types :: Integer attribute :name , Types :: String attribute :created_at , Types :: JSON :: Time attribute :updated_at , Types :: JSON :: Time end def by_name ( name ) append_path ( name ) end end end end config . register_relation ( GitHub :: Resources :: Organizations ) rom = ROM . container ( config )

We only defined a sub-set of all the attributes, mappers will reject extra keys for us and give us back simpler data structures. Notice the by_name view in this class - it appends organization name to the base path. For example org/rom-rb is the path we want to use to find an organization named rom-rb .

Relation#append_path is just one of the many convenient methods that are available, that will help you in constructing HTTP queries. Refer to API documentation for more information.

Let's see this in action now:

orgs = rom . relations [ :orgs ] # Plain hashes by default unless you set `auto_struct true` globally orgs . by_name ( 'rom-rb' ). one # {:id=>4589832, :name=>"rom-rb", :created_at=>2013-06-01 22:03:54 UTC, :updated_at=>2019-04-03 14:36:48 UTC} # Auto-structs on demand orgs . with ( auto_struct: true ). by_name ( 'rom-rb' ). one # #<ROM::Struct::Org id=4589832 name="rom-rb" created_at=2013-06-01 22:03:54 UTC updated_at=2019-04-03 14:36:48 UTC>

Sweet. Data automatically converted to the exact format that we wanted to have, with unspecified keys rejected and attribute values coerced to configured types.

Release Information

For more information refer to the CHANGELOG.

Give this adapter a try and tell us what you think!