# mashery_rails

[![Coverage Status](https://coveralls.io/repos/farleyknight/mashery_rails/badge.png)](https://coveralls.io/r/farleyknight/mashery_rails)
[![Build Status](https://travis-ci.org/farleyknight/mashery_rails.png?branch=master)](https://travis-ci.org/farleyknight/mashery_rails)
[![Code Climate](https://codeclimate.com/github/farleyknight/mashery_rails.png)](https://codeclimate.com/github/farleyknight/mashery_rails)

A Rails library for the [Mashery API](http://support.mashery.com/docs/mashery_api).

Includes:

* `config/mashery.yml` config file
* A simple Query generator for the RPC API, and it's SQL-esque syntax
* Good test coverage

## Installation

Add the following to your `Gemfile`

```ruby
gem "mashery_rails", require: "mashery"
```

Then run the installer to create `config/mashery.yml`

```bash
$ rails g mashery:install
```

## Configuration

Edit `config/mashery.yml` with your `site_key`, `key` and `secret` options.

```yaml
---
site_id: '123'
key: "abc"
secret: "xyz"
host: "api.mashery.com"
```

Note this doesn't distinguish between development, testing, production, etc. If you really need that functionality, open a new issue.

## JSON-RPC API

The central data objects are all listed on the [RPC API documentation page](http://support.mashery.com/docs/read/mashery_api/20/API_Objects), and should be supported. However, [fetching objects](http://support.mashery.com/docs/read/mashery_api/20/Fetching_Objects) are the main & typically only supported method for each of these objects. If you feel you want to support more methods, feel free to create a pull request.

### `all`

Fetch the first 100 objects of a particular type. The 100 objects constraint is caused by [Mashery](http://support.mashery.com/docs/read/mashery_api/20/Query_Language):

> Query results are always paginated.  There is a limit of fetching 100 records at one time.  By default, only the first 100 records are returned.

```ruby
Mashery::Member.all #=>
```

### `find_each`

Much like `ActiveRecord::Base.find_each`, this will take a block and auto-paginate the object set, working around the 100 items per page limitation stated above.

```ruby
Mashery::Member.find_each {|m| m.do_something! }
```

### `first`

Fetch the first object of a particular type. This is effectively setting "ITEMS 1" and reifying that object.

```ruby
Mashery::Member.first #=>
```

### `count`

The total number of objects.

```ruby
Mashery::Member.count #=>
```

## Query Language

Mashery has a basic SQL-like Query Language. This library provides basic AREL-like functionality to build those queries. One small, but important difference is lack of lazy loading. These methods produce queries, but you have to call `all` in order to retrieve the objects.

### `select`

Change the SELECT fragment of the query.

```ruby
Mashery::Member.select("name") #=>
```

### `where`

Change the WHERE fragment of the query.

```ruby
Mashery::Member.where(name: "User Name")

#=> SELECT * FROM members WHERE name = 'User Name' ITEMS 100
```

### `items`

Change the ITEMS fragment of the query.

```ruby
Mashery::Member.items(10)

#=> => SELECT * FROM members ITEMS 10
```

### `page`

Change the PAGE fragment of the query.

```ruby
Mashery::Member.page(10)

#=> SELECT * FROM members PAGE 10 ITEMS 100
```

## REST API

Mashery's REST API are mostly calls based on service objects.