ApiMapper
ApiMapper converts API resources into ruby objects
Installation
Warning: This is work in progress. Public API will probably change
Add this line to your application's Gemfile:
gem 'api_mapper'
And then execute:
$ bundle
Or install it yourself as:
$ gem install api_mapper
Usage
# Github example
class User
attr_reader :id, :login
def initialize(id, login)
@id, @login = id, login
end
end
# simple mapper
# Mapper have to provide `call` method that accepts array as an argument
class UserMapper
def call(origin)
origin.map { |attributes| User.new(attributes["id"], attributes["login"]) }
end
end
class Repository
include Virtus.model
attribute :id, Integer
attribute :name
attribute :full_name
attribute :owner, User
end
# Example of complex mapper using faceter gem (https://github.com/nepalez/faceter)
class RepositoriesMapper < Faceter::Mapper
list do
symbolize_keys
create :owner, from: [:owner] do |owner|
UserMapper.new.call(owner)
end
wrap to: :attributes, only: [:id, :name, :full_name, :owner]
create from: [:attributes] do |attributes|
Repository.new(attributes)
end
end
end
class Router < ApiMapper::Router
get "user", UserMapper.new
patch "user", UserMapper.new
get "repositories", RepositoryMapper.build
end
# client setup
client = ApiMapper::Client.new('https://api.github.com')
client.router = Router.new
client.("token secret_token")
# get profile
profile = client.get('user')
profile.login # martinciu
profile.hireable # false
# update profile
profile.hireable = true
updated_profile = client.patch('user', profile)
updated_profile.hireable = true
# get list of repositories
repositories = client.get('repositories')
repository = repositories.first
repository.id # 1
repository.name # grit
repository.full_name # mojombo/grit
repository.user.id # 1
repository.user.login # mojombo
# Moves app example (complex mapper)
class Profile
include Virtus.model
attribute :id, Integer
attribute :created_at, Date
attribute :locale, String
attribute :metric, Boolean
end
# {
# "userId": 23138311640030064,
# "profile": {
# "firstDate": "20121211",
# "currentTimeZone": {
# "id": "Europe/Helsinki",
# "offset": 10800
# },
# "localization": {
# "language": "en",
# "locale": "fi_FI",
# "firstWeekDay": 2,
# "metric": true
# },
# "caloriesAvailable": true,
# "platform": "ios"
# }
# }
# Example of complex mapper using rom-mapper gem (https://github.com/rom-rb/rom-mapper)
class ProfileMapper < ROM::Mapper
reject_keys true
attribute :id, from: "userId"
unwrap "profile" do
attribute :created_at, from: "firstDate"
attribute :metric
attribute :locale
unwrap "localization" do
attribute :metric, from: "metric"
attribute :locale, from: "locale"
end
end
model Profile
end
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/martinciu/api_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.
License
The gem is available as open source under the terms of the MIT License.