citygrid_api

= citygrid

Not stable yet. Use at your own risk!

== Getting Started

=== Installation

This gem is still under very active development. As such, you can obtain the latest by directly installing from github:

gem "citygrid_api", :git => "git://github.com/CityGrid/citygrid_api.git"

You can get a relatively stable build from rubygems.org. Specifying a version number is highly recommended as there will be breaking changes until we stabilize.

gem "citygrid_api", "0.0.6"

=== Configuration

Add a file called citygrid_api.rb under config/initializers.

Configure the gem to use your publisher code with:

CityGrid.publisher = 'your_publisher_code'

Additional options are available such as:

CityGrid.print_curls = true/false CityGrid.custom_timeout = 20 #time in seconds CityGrid.raise_errors = true/false

If you don't have a publisher code, you can obtain one at http://developer.citygridmedia.com

Move citygrid_api.yml.sample into your project. This file configures the API endpoints. Load the configuration with:

CityGrid.load_config 'path/to/config/yml'

== Sessions

Most methods require an AuthToken. This is obtained by either using the CityGrid::Session class (preferred) or CityGrid::API::Accounts::Account.login, which would require managing your own AuthToken.

An authenticated session can be obtained with

session = CityGrid.session 'username', 'password'

Once authenticated, the session will automatically pass along the AuthToken to API methods that require it when you use the call_api method

session.call_api CityGrid::API::Advertising::Category, :search, :keywords => "pizza"

This corresponds to

auth_token = 'my_auth_token' # obtained by calling CityGrid::API::Accounts::Account.login CityGrid::API::Advertising::Category.search :token => auth_token, :keywords => "pizza"

In the future, AuthTokens may be invalidated and there may be other methods to log in. Session and call_api will handle that for you.