serviceable

Serviceable

Serviceable aims to reduce code duplication for common patterns, such as JSON/XML API endpoints. Instead of repeating the same patterns in multiple controllers and trying to maintain that over time, we extracted those patterns into a module.

Configuration:

gem 'serviceable'

Controller:

class PostsController < ApplicationController

  include Serviceable
  acts_as_service :post

end

Basic Routes:

resources :posts

Advanced Feature Routes:

resources :posts do
  collection do
    get :count
    get :describe
  end
end

Standard CRUD

POST /posts.json
GET /posts.json
GET /posts/1.json
PUT /posts/1.json
DELETE /posts/1.json

Advanced Features

Retrieve the number of records using the given query params

GET /posts/count.json
86

Use query params to filter the set

GET /posts/count.json?where[posts][author_id]=123
14

Discover the available extensions beyond basic CRUD, such as allowed includes and methods

GET /posts/describe.json
{"allowed_includes":["tags","author"],"allowed_methods":[]}

Query Params

Full listing returned when no query params are given

GET /posts.json
[{"id":1,"title":"First Post!","body":"Feels good to be first","created_at":"20130727T16:26:00Z"}]

Use the only and/or except params to specify fields on the collection

GET /posts.json?only=id,title
[{"id":1,"title","First post!"}]

Use the include param to specify associated objects or collections

GET /posts.json?include=user
[{"id":1,"title":"First Post!","body":"Feels good to be first","created_at":"20130727T16:26:00Z","user":{"id":2,"first_name":"Jim","last_name":"Walker","display_name":"Jim W."}}]

Use the methods param to include the return values from a set of methods on each object

GET /posts.json?methods=max_rating
[{"id":1,"title":"First Post!","body":"Feels good to be first","created_at":"20130727T16:26:00Z","max_rating":3}]

Combine params to configure the result contents

GET /posts.json?only=id,title&include[user][only]=first_name,last_name
[{"id":1,"title":"First Post!","user":{"first_name":"Jim","last_name":"Walker"}}]

Filter Params

Use the where param to filter the results

GET /posts.json?where[posts][published]=true

Use associated objects or collections to filter the set

GET /posts.json?where[tags][label]=Pinball

Integrating with jQuery

Working with a serviceable endpoint is easy with jQuery. Here's an example of a request for all posts tagged as "Pinball" including only post id and title:

$.ajax({
  url: '/posts.json',
  type: 'GET',
  data: {
    where: {
      tags: {
        label: 'Pinball'
      }
    },
    only: 'id,title'
  },
  success: function(xhr,msg,data) {
    console.log("received "+data.responseJSON.length+" results");
  }
});