ResponseMapper

These days we all deal with many different APIs; It can be either third-party services, or our own microservices. Not all of them are well-designed and sometimes their attributes are named inconsistently.

ResponseMapper allows you to map attributes from an API response to your application’s domain language.

{ "orderNumber" => 10, "orderItems" => [{ "orderItemId" 1, "itemTitle" "Book" }] }

{ id: 10, items: [{ id: 1, title: "Book" }] }

Using the example above let’s look at a response we may get from a 3rd party API:

response = JSON.parse(response_from_api)
# => { "orderNumber" => 10, "orderItems" => [{ "orderItemId" 1, "itemTitle" "Book" }] }

1. Map response, so we can easily instantiate entity from response.
2. Symbolize keys to keep things consistent.

mapping = { orderNumber: :id, orderItems: :items, orderItemId: :id, itemTitle: :title }

order_attributes = ResponseMapper.map(data: response, mapping: mapping)
# => { id: 10, items: [{ id: 1, title: "Book" }] }

Now we have a nice Hash with symbolized keys that correspond to attributes of Order in our system. For example further step could be just wrap this hash into Order entity:

Entity::Order.new(order_attributes)

ResponseMapper maps and symbolizes keys even for nested arrays and hashes. It will work for more complex responses.

See more examples here.

Add this line to your application's Gemfile:

gem 'response_mapper'

And then execute:

$ bundle

Or install it yourself as:

$ gem install response_mapper

ResponseMapper provides one class method .map which has two required params: data and mapping. There is one optional parameter: symbolize_keys which is set to true by default.

ex.

order_attributes = ResponseMapper.map(data: response, mapping: mapping)

data can be anything, but ResponseMapper will try to map it only if it's a Hash or Array. If it's not a Hash or Array - ResponseMapper will return data as is.

mapping should be a Hash with attributes you want to map:

mapping = { orderNumber: :id, orderItems: :items, orderItemId: :id, itemTitle: :title }

It will map any occurrence of :order_number in data to :id. If mapping is not a Hash (or empty Hash) - ResponseMapper will raise ResponseMapper::Error.

sybmolize_keys is set to true by default. If your data contains hashes with strings as keys, they will be symbolized and then mapped.

See more examples here.

If you want to learn more, read an article on how ResponseMapper can help to protect naming conventions when working with microservices or third-party API.

Bug reports and pull requests are welcome on GitHub at https://github.com/smakagon/response_mapper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.