README.md

Resourcey

A lightweight rails gem for building resource-based APIs. It gives you some conventions and convenient solutions for rendering resources in JSON format.

Table of contents

• Requirements
• Installation
• Usage
  • Controller
  • Serialization
  • How to fetch
  • Pagination
  • Filtering
• Configuration
• Contributing

Requirements

Resourcey requires ruby 2.2.2 or higher.

Installation

Add Resourcey to your Gemfile:

gem 'resourcey'

And then:

bundle

Or install it manually:

gem install resourcey

Usage

Controller

For a resource called user, just create UsersController:

class Api::V1::UsersController < Resourcey::Controller
end

For further reading, click here.

Serialization

Now you need a serializer, let's assume that User has an email and an ID, go with this:

class UserSerializer < Resourcey::Serializer
  attributes :id, :email
end

For further reading, click here.

Fetch the data

Don't forget to create a correct route in your routes.rb file, and you're good to go! Now just visit /api/v1/users, and see how your resources are rendered.

/* example response */

[
  { "id": 1, "email": "[email protected]" },
  { "id": 2, "email": "[email protected]" }
]

Pagination

To paginate resources, simply invoke paginate method in controller, like this:

class ResourcesController < Resourcey::Controller
  paginate
end

This will use default :paged paginator. Now you need to pass page and per_page parameters in pagination parameter value, like this:

http://api.example.com/resources?page=3&per_page=10

This will fetch page 3, with 10 resources per single page. That's all! Pagination can be configured globally (see "Configuration" below). Also you can configure every controller's pagination.

For further reading, click here.

Filtering

You can filter your resources using filter objects defined per single resource model. See below for an example:

class UserFilter < Resourcey::Filter
  filter :older_than do |value, scope|
    scope.where('users.age > ?', value)
  end
end

For further reading, click here.

Configuration

Create configuration file in your config/initializers folder, and configure as usual:

Resourcey.configure do |config|
  config.some_config_variable = :some_value
end

Available config variables

config var	description	default
default_paginator	Name of paginator that will be used in every controller, if not configured on controller-level. Click here for details.	:paged
controller_parent	Class or class name of controller, that Resourcey::Controller will inherit from.	ActionController::Base

Contributing

If you want to take part in developing resourcey, fork this repository, commit your code, and create pull request.

Requirements

• ruby 2.2.2 or higher
• bundler gem

Running local tests

• rspec