Logo

Gem Version Maintainability Build Status codecov

Table of Contents

What is Resting Pug?

Resting Pug allows you to create a JSON API with just adding one line to your controller and fully customize it with overriding small and simple helper methods.

Why should I use it?

Often when you want to try a new idea or create a simple app you want to implement basic features very fast. Resting Pug allows you to do it with just couple lines of code. But even though it is small and simple(and because it is small and simple) you can vastly customize created API. Attributes user can see, attributes user can edit, number of items on page, how to render items and errors - thats just a small part of things you can change overriding basic Resting Pug methods.

Installation

Add this line to your application's Gemfile:

gem 'resting_pug'

And then execute:

$ bundle

Usage

1. Create a model that will be accesible through API:

class Book < ApplicationRecord
  validates :title, presence: true, length: { minimum: 3 }
  validates :author, presence: true, length: { minimum: 3 }
end

class CreateBooks < ActiveRecord::Migration
  def change
    create_table :books do |t|
      t.string :title
      t.string :author
      t.integer :year
      t.integer :rating

      t.timestamps
    end
  end
end

2. Create a new controller and include RestingPug::Base into it to add CRUD actions:

class BooksController < ApplicationController
  include RestingPug::Base
end

You can add CRUD actions to all controllers by including this module into ApplicationController:

class ApplicationController < ActionController::Base
  include RestingPug::Base
end

3. Don't forget to add a route to config/routes.rb

Rails.application.routes.draw do
  resources :books
end

4. Enjoy your new API and don't hesitate to change it whatever you want!

List of actions and things that you can customize

Actions created after including RestingPug::Base:

Create

Request:
POST http://your.awesome/api/books
{
  "name": "11/22/63",
  "author": "Stephen King"
}

Response:
200 OK
{
  "book": {
    "id": 1,
    "name": "11/22/63",
    "author": "Stephen King"
  }
}

Things you can customize:

Update

Request:
PATCH http://your.awesome/api/books/1
{
  "name": "The Green Mile",
}

Response:
200 OK
{
  "book": {
    "id": 1,
    "name": "The Green Mile",
    "author": "Stephen King"
  }
}

Things you can customize:

Destroy

Request:
DELETE http://your.awesome/api/books/1

Response:
204 No Content

Things you can customize:

  • override destroy_subject to set how it will be destroyed
  • override render_nothing to set what to render when subject is destroyed
  • override render_errors to set how errors will be rendered
  • override render_not_found to set what to render when subject with ID from params is not found
  • override subject_model to set what model will be deleted
  • override destroy_chain to add or remove methods which will be called while deleting a subject

Show

Request:
GET http://your.awesome/api/books/1

Response:
200 OK
{
  "book": {
    "id": 1,
    "name": "The Green Mile",
    "author": "Stephen King"
  }
}

Things you can customize:

Index

Request:
GET http://your.awesome/api/books
GET http://your.awesome/api/books?filter[author]="King"
GET http://your.awesome/api/books?filter[author][]="King"&filter[author][]="Kesey"
GET http://your.awesome/api/books?sort=-id,name,-author
GET http://your.awesome/api/books?page=3&per_page=10
GET http://your.awesome/api/books?filter[author]="King"&sort=-id?page=3&per_page=10

Response:
200 OK
{
  "books": [{
    "id": 2,
    "name": "The Green Mile",
    "author": "Stephen King"
  }, {
    "id": 1,
    "name": "11/22/63",
    "author": "Stephen King"
  }]
}

Things you can customize:

Contributing

You're encouraged to submit pull requests, propose features and discuss issues.

See CONTRIBUTING

Changelog

To see what has changed in recent versions of Resting Pug, see the CHANGELOG.

License

The gem is available as open source under the terms of the MIT License.

Logo is Designed by Freepik