ResoWebApi
A Ruby library to connects to MLS servers conforming to the RESO Web API standard.
Installation
Add this line to your application's Gemfile:
gem 'reso_web_api'
And then execute:
$ bundle
Or install it yourself as:
$ gem install reso_web_api
Usage
Quickstart
Instantiating an API client requires two things: an endpoint (i.e. service URL) and an authentication strategy.
require 'reso_web_api'
client = ResoWebApi::Client.new(endpoint: '<Service URL>', auth: auth)
The :endpoint
option should need no further explanation, for :auth
, read on below.
Authentication
You may either instantiate the auth strategy directly and pass it to the client constructor (in the :auth
parameter), or you may choose to pass a nested hash with options for configuring the strategy instead, as below:
client = ResoWebApi::Client.new(
endpoint: 'https://api.my-mls.org/RESO/OData/',
auth: {
strategy: ResoWebApi::Authentication::TokenAuth,
endpoint: 'https://oauth.my-mls.org/connect/token',
client_id: 'deadbeef',
client_secret: 'T0pS3cr3t',
scope: 'odata'
}
end
Note that if you choose this option, you may specify the strategy implementation by passing its class as the :strategy
option.
If you omit the :strategy
parameter, it will default to ResoWebApi::Authentication::TokenAuth
.
For a list of available authentication strategies and usage examples, please see below.
Advanced Configuration
The client is designed to work out-of-the-box and require as little configuration as possible (only endpoint and auth by default). However, if you need more control, there are several additional settings that can be configured using the constructor.
-
:user_agent
: Sets theUser-Agent
header sent to the service (defaults toReso Web API Ruby Gem $VERSION
) -
:adapter
: Sets the Faraday adapter used for the connection (defaults toNet::HTTP
) -
:headers
: Allows custom headers to be set on the connection. -
:logger
: You may pass your own logger to a client instance. By default, each instance will use the global logger defined on theResoWebApi
module, which logs to STDOUT. You can also change the logger on the module itself, which will then be used for all new client instances you create. -
:odata
: If you need to pass any special options to the OData service, you may do so here.
Accessing Data
Standard Resources
Since most RESO Web API servers will likely adhere to the RESO Data Dictionary, we've created some shortcuts for the standard resources
# Iterate over all properties -- WARNING! Might take a long time
client.properties.each do |property|
puts "#{property['ListPrice']} #{property['StandardStatus']}"
end
The following methods are provided:
- Property: use
#properties
- Member: use
#members
- Office: use
#office
- Media: use
#media
Other Resources
Other resources may be access using the #resources
method on the client, which may be accessed as a hash like this:
client.resources['OpenHouse'].first # Access the 'OpenHouse' collection
Authentication Strategies
Since the details of authentication may vary from vendor to vendor, this gem attempts to stay flexible by providing a modular authentication system.
Available Strategies
Currently, we provide the following authentication strategies:
SimpleTokenAuth
A simple strategy that works with a static access token. Often used for development access, where security is not a major concern.
Configuration
-
access_token
: The access token value (String
). -
token_type
: The token type (String
, optional). Defaults toBearer
.
Example
client = ResoWebApi::Client.new(
endpoint: 'https://api.my-mls.org/RESO/OData/',
auth: {
strategy: ResoWebApi::Authentication::SimpleTokenAuth,
access_token: 'abcdefg01234567890'
}
)
TokenAuth
A basic OAuth-based token strategy, where a Client ID/Secret pair is sent to a server in exchange for a temporary access token. Frequently used in production systems for its increased security over the static token strategy.
Configuration
-
endpoint
: The URL of the token server (String
). -
client_id
: The Client ID (String
). -
client_secret
: The Client Secret (String
). -
scope
: The scope for the token (String
). -
grant_type
: The grant type (String
, optional). Defaults toclient_credentials
.
Example
client = ResoWebApi::Client.new(
endpoint: 'https://api.my-mls.org/RESO/OData/',
auth: {
strategy: ResoWebApi::Authentication::TokenAuth,
endpoint: 'https://oauth.my-mls.org/connect/token',
client_id: 'deadbeef',
client_secret: 'T0pS3cr3t',
scope: 'odata'
}
end
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
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/wrstudios/reso_web_api.
License
The gem is available as open source under the terms of the MIT License.