flexmls API

A Ruby wrapper for the flexmls REST API. Loosely based on ActiveResource to provide models to interact with remote services.

Documentation

For full information on the API, see http://www.flexmls.com/developers/

Installation

gem install flexmls_api

Usage Examples

Ruby Script

# initialize the gem with your key/secret
# api_key and _api_secret are the only required settings
# other options and their defaults:
#  - endpoint:   'http://api.flexmls.com'  
#  - version:    'v1'
#  - ssl:         false
#  - user_agent: 'flexmls API Ruby Gem'
FlexmlsApi.configure do |config|
    config.endpoint   = 'http://api.developers.flexmls.com'
    config.api_key    = 'my_api_key'
    config.api_secret = 'my_api_secret'
end

# mixin the models so you can use them without prefix
include FlexmlsApi::Models

# Grab your listings!
my_listings = Listing.my()

Interactive Console

Included in the gem is a simple setup script to run the client in IRB. To use it, first create the file called .flexmls_api_testing filling in the credentials for your account.

API_ENDPOINT="http://api.developers.flexmls.com"
API_KEY="my_api_key"
API_SECRET="my_api_secret"

export API_USER API_ENDPOINT API_KEY API_SECRET

Now, to run with this setup, run the following from the command line:

> source .flexmls_api_testing
> flexmls_api
flemxlsApi> FlexmlsApi.client.get '/my/account'

You can also provide these options from the command line, see "flexmls_api -h" for more information

Authentication Types

Authentication is handled transparently by the request framework in the gem, so you should never need to manually make an authentication request. More than one mode of authentication is supported, so the client needs to be configured accordingly.

API Authentication (Default)

Usually supplied for a single user, this authentication mode is the simplest, and is setup as the default. The example usage above demonstrates how to get started using this authentication mode.

OAuth2 Authentication

Authentication mode the separates application and user authentication. This mode requires further setup which is described in lib/flexmls_api/authentication/oauth2.rb

Error Codes

HTTP Code	flexmls API Error Code	Exception Raised	Description
401	1000		Invalid API Key and/or Request signed improperly
401	1010		API key is disabled
403	1015		ApiUser must be supplied, or the provided key does not have access to the supplied user
401	1020		Session token has expired
403	1030		SSL required for this type of request
400	1035		POST data not supplied as valid JSON. Issued if the Content-Type header is not application/json/ and/or if the POST data is not in valid JSON format.
400	1040		The _filter syntax was invalid or a specified field to search on does not exist
400	1050		(message varies) A required parameter was not provided
400	1053		(message varies) A parameter was provided but does not adhere to constraints
409	1055		(message varies)Issued when a write is requested that will conflict with existing data. For example, adding a new contact with an e-mail that already exists.
403	1500		The resource is not available at the current API key's service level. For example, this error applies if a user attempts to access the IDX Links API via a free API key.
503	1550		Over rate limit