sweet_actions 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3904d237f789cd3db0a4dc78e4f9adecc8bf3b9a
+  data.tar.gz: 4231ace1119c75b32e0c57dd8f7ac33e1e02051a
+SHA512:
+  metadata.gz: abc3087589ceed04b51f4e60b7fcb2485c4f96049bc7c029d3b9feaca16f1449d7518c328631f9c4a3dc8420d78c84f8701d48085e4361ccbfaa991450ff54af
+  data.tar.gz: 57c3d381618502950e5e1301ede3de0d048890cb86a18280924632f661d9dd504c5ae50e7381918363cb76bb170747f79267e21f0c7f43ab202c796f46d361aa

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.14.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sweet_actions.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Ryan Francis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PITCHME.md

@@ -0,0 +1,224 @@
+---
+
+# Sweet Actions
+#### a Ruby on Rails Gem
+
+---
+
+## Let's REST not STRESS
+
+Implementing a REST JSON API should be:
+
+- easy
+- consistent
+- secure
+- extendable
+
+---
+
+## Job to be Done
+
+What is the Job that REST is solving?
+
+- Users need to interact with our database
+- They can do so by either creating a new record or reading, updating, or destroying an existing record (CRUD)
+
+---
+
+For example, given an **Events** resource:
+
+- See an event
+- See a list of events
+- Create an event
+- Update an event
+- Delete an event
+
+---
+
+## The Big 5
+
+- show
+- index
+- create
+- update
+- destroy
+
+---
+
+## Good News
+
+Consistency = easy to program
+
+...or at least it should be
+
+---
+
+## Current Process
+
+We are focused on the **resource** instead of the **action**
+
+```ruby
+class EventsController
+  def index; end
+  def show; end
+  def create; end
+  def update; end
+  def destroy; end
+end
+```
+
+**resource = class, actions = methods**
+
+---
+
+## But wait...
+
+Which do you think has more in common?
+
+1. events#create <=> events#index
+2. events#create <=> articles#create
+
+---
+
+```ruby
+class EventsController
+  def create
+    event = Event.new(event_params)
+    raise NotAuthorized unless can?(:create, event)
+
+    if event.save
+      # success
+    else
+      # failure
+    end
+  end
+
+  def index
+    events = Event.where(date: >= Date.today)
+    serialize(events)
+  end
+end
+```
+
+---
+
+```ruby
+class EventsController
+  def create
+    event = Event.new(event_params)
+    raise NotAuthorized unless can?(:create, event)
+
+    if event.save
+      # success
+    else
+      # failure
+    end
+  end
+end
+
+class ArticlesController
+  def create
+    article = Article.new(article_params)
+    raise NotAuthorized unless can?(:create, article)
+
+    if article.save
+      # success
+    else
+      # failure
+    end
+  end
+end
+```
+
+---
+
+## Answer: #2
+
+```ruby
+'events#create' == 'articles#create'
+'events#create' != 'events#index'
+```
+
+---
+
+### Actions as First Class Citizens
+
+Since the actions have more in common with each other than they do with the resources to which they belong, it is the actions that should be objects instead of the resource.
+
+---
+
+```ruby
+class CreateAction < SweetActions::CreateAction
+  def action
+    resource = set_resource
+    resource.save ? success : failure
+  end
+
+  private
+
+  def set_resource
+    resource_class.new(resource_params)
+  end
+
+  def resource_params
+    decanter.new(params[resource_name])
+  end
+end
+```
+
+---
+
+```ruby
+module Events
+  class Create < CreateAction
+    def after_save
+      UserMailer.send_event_confirmation.deliver_later
+    end
+  end
+end
+```
+
+---
+
+## Demo
+
+1. Install gem
+2. Generate resource (model, decanter, serializer, actions)
+3. Add routes
+
+---
+
+## 1. Install Gem
+
+Gemfile:
+
+```ruby
+gem 'sweet_actions'
+```
+
+Terminal:
+
+```
+bundle
+```
+
+---
+
+## 2. Generate Resource
+
+```
+rails g model Event title:name start_date:date
+rails g decanter Event title:name start_date:date
+rails g serializer Event title:name start_date:date
+rails g actions Events
+```
+
+---
+
+## 3. Add Routes
+
+```ruby
+Rails.application.routes.draw do
+  create_sweet_actions(:events)
+end
+```

data/PITCHME.yaml

@@ -0,0 +1 @@
+# theme : black

data/README.md

@@ -0,0 +1,257 @@
+# Sweet Actions
+
+## The Idea
+
+In a RESTful context, controller actions tend to have more in common with the same actions belonging to other resources than other actions belonging to the same resource. For example, let's say we have two resources in our app: Events and Articles.
+
+Which do you think has more in common in terms of programming logic?
+
+1. events#create <=> events#index
+2. events#create <=> articles#create
+
+We would argue that #2 has more in common than #1. Both events#create and articles#create need to do the following:
+
+1. Authorize the transaction
+2. Validate the data
+3. Persist the new record
+4. Respond with new record (if successful) or error information (if unsuccessful) in the JSON
+
+By organizing our actions as methods inside a resource based controller like below, we don't have the opportunity to take advantage of basic Object Oriented programming concepts like Inheritance and Modules.
+
+```ruby
+class EventsController < ApplicationController
+  # more similar to articles#create than events#index
+  def create
+    event = Event.new(event_params)
+    raise NotAuthorized unless can?(:create, event)
+
+    if event.save
+      UserMailer.new_event_confirmation(event).deliver_later
+      serialize(event)
+    else
+      serialize_errors(event)
+    end
+  end
+
+  # more similar to articles#index than events#create
+  def index
+    events = Event.where(date: >= Date.today)
+    serialize(events)
+  end
+end
+
+class ArticlesController < ApplicationController
+  # more similar to events#create than articles#index
+  def create
+    article = Article.new(article_params)
+    raise NotAuthorized unless can?(:create, article)
+
+    if article.save
+      serialize(article)
+    else
+      serialize_errors(article)
+    end
+  end
+
+  # more similar to events#index than articles#create
+  def index
+    articles = Article.where(published: true)
+    serialize(articles)
+  end
+end
+```
+
+Instead, we propose a strategy that looks more like the following:
+
+```ruby
+# generic logic for create (sweet_actions gem)
+module SweetActions
+  class CreateAction < ApiAction
+    def action
+      @resource = set_resource
+      authorize
+      validate_and_save ? success : failure
+    end
+
+    # ...
+  end
+end
+
+# app logic for create (app/actions/create_action.rb)
+class CreateAction < SweetActions::CreateAction
+  def set_resource
+    resource_class.new(resource_params)
+  end
+
+  def authorized?
+    can?(:create, resource)
+  end
+end
+
+# resource logic for create (app/actions/events/create.rb)
+module Events
+  class Create < CreateAction
+    def after_save
+      UserMailer.new_event_confirmation(resource).deliver_later
+    end
+  end
+end
+```
+
+With this structure, we essentially have three levels of abstraction:
+
+- Generic create logic: SweetActions::CreateActions
+- App create logic: CreateAction
+- Resource create logic: Events::Create
+
+
+As you can see, we can abstract most of the `create` logic to be shared across resources, which means you **only need to write the code that is unique about this create action vs. other create actions**.
+
+## Default REST Actions
+
+For a given resource...
+- Collect: list items
+- Create: create new item
+- Show: show item
+- Update: update item
+- Destroy: delete item
+
+Many of these actions have shared behavior, which we abstract for you:
+- All require serialization of the resource
+- Create and Update need to be able to properly respond with error information when save does not succeed
+- Create and Update rely on decanted params
+- All require authorization (cancancan)
+
+## Automatic REST API
+
+Given an Event model, one can do the following and get a basic RESTful API (assuming we have [decanter](https://github.com/launchpadlab/decanter) and [AMS](https://github.com/rails-api/active_model_serializers):
+
+- rails g model Event name:string start_date:date
+- rails g decanter Event name:string start_date:date
+- rails g serializer Event name:string start_date:date
+- add the new resource in routes
+
+With that, you have the following at your disposal:
+
+Collect: get '/events'
+Create: post '/events'
+Show: get '/events/:id'
+Update: put '/events/:id'
+Destroy: delete '/events/:id'
+
+Each of these will respond with a consistent JSON format, including when saves don't succeed.
+
+## Overriding Default Actions
+
+Should you choose to override the default behavior (defined in app/sweet_actions/defaults/, ), you need only create your own action like so:
+
+app/sweet_actions/events/collect.rb
+
+```
+module Events
+  class Collect < SweetActions::CollectAction
+    def set_resource
+      Event.all.limit(10)
+    end
+
+    def authorized?
+      can?(:read, resource)
+    end
+  end
+end
+```
+
+app/sweet_actions/events/create.rb
+
+```
+module Events
+  class Create < CreateAction
+    def set_resource
+      Event.new(resource_params)
+    end
+
+    def authorized?
+      can?(:create, resource)
+    end
+
+    def save
+      resource.save
+    end
+
+    def after_save
+      SiteMailer.notify_user
+    end
+  end
+end
+```
+
+app/sweet_actions/events/show.rb
+
+```
+module Events
+  class Show < ShowAction
+    def set_resource
+      Event.find(params[:id])
+    end
+
+    def authorized?
+      can?(:read, resource)
+    end
+  end
+end
+```
+
+app/sweet_actions/events/update.rb
+
+```
+module Events
+  class Update < UpdateAction
+    def set_resource
+      Event.find(params[:id])
+    end
+
+    def authorized?
+      can?(:update, resource)
+    end
+
+    def save
+      resource.update(resource_params)
+    end
+  end
+end
+```
+
+app/sweet_actions/events/destroy.rb
+
+```
+module Events
+  class Destroy < DestroyAction
+    def set_resource
+      Event.find(params[:id])
+    end
+
+    def authorized?
+      can?(:destroy, resource)
+    end
+
+    def destroy
+      resource.destroy
+    end
+  end
+end
+```
+
+## Installation
+
+Gemfile:
+
+```
+gem 'sweet_actions'
+```
+
+Terminal:
+
+```
+bundle
+bundle exec rails g sweet_actions:install
+```