cathode 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4d84a893f57e8bb3db9121ed7c77b5129b097332
+  data.tar.gz: 0ac0b4a4164c8eff2324e3dc394b220110f1d7dc
+SHA512:
+  metadata.gz: 8595c76223683aa134f22aeb9498569706ac4059f2b738e1420cb0603533aaae5327c93ee1ccfc7a2ee27b66dfde1323e38509da7de3c8a75d8976bea16e1455
+  data.tar.gz: 1bd851d2603db7b9c0ab5e0d07e2f64620c10cd52b48212e714fa9b99082d1ab9900e29666d2692f6cd855bed2880b95e8aa0a246529306865e21b276bcfea60

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Moby, Inc.
+
+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/README.md

@@ -0,0 +1,236 @@
+**This gem is under heavy development and is not ready to be used in product
+systems.**
+
+# Cathode
+Cathode is a gem for Rails projects that generates API boilerplate for REST
+applications.
+
+## Features
+* Automatically generate endpoints (routes + controllers) for common RESTful
+  actions:
+  * Listing resources, optionally filtered and paginated
+  * Finding a single resource
+  * Creating a new resource
+  * Updating a resource
+  * Deleting a resource
+* Endpoints respond to JSON and output JSON by default (possibly add XML et al later on?)
+* Versioning of endpoints
+* Deprecation
+* Auto-documentation
+
+## Getting Started
+To generate the `api` directory and mount the engine:
+```ruby
+rails generate cool
+```
+
+*Note: Your API can be defined using the `resource` method in your `api/api.rb` file,
+using separate files and the `Cathode::API` class, or a combination of both. For
+brevity, this document uses `resource` with the assumption that everything is in
+`api.rb`. See the section below, “Files & Naming Conventions,” for details on
+using the other method.*
+
+In the simplest case, you can use only default actions:
+```ruby
+resource :products, actions: [:index, :show, :search]
+```
+
+Contrary to Rails’s `routes.rb` file–in which the default actions are included
+unless explicitly excluded–only actions that you specify are defined. Out of
+the box, the actions available are: `:index, :show, :create, :update, :delete, :search`.
+
+In this case, the following routes are created: `get api/products/`, `get
+api/products/{id}`, and `get api/products/search`. By default, all products will
+be returned in the `index` call, and no permissions will be enforced on the
+`show` call. By default, the `search` call will take a `query` parameter and
+search for it using the `Product.title` field.
+
+## Serialization
+Cathode doesn’t do any explicit serialization of resources when responding to
+requests. However, it does use `render: json`, which will invoke [ActiveModel
+serializers](https://github.com/rails-api/active_model_serializers) if you’ve
+defined them.
+
+## Versioning
+Versioning is encouraged to prevent you from introducing breaking API changes.
+Your API’s versions should use [Semantic Versioning](http://semver.org/), which
+enables Cathode to deduce patches, non-breaking changes, and breaking changes. Cathode
+also makes it easy to deprecate all or part of any version of your API at any
+time.
+
+If you define your resources without any versions, Cathode assumes it’s version
+`1.0.0` of your API. When you’re ready to introduce changes, you can
+easily provision a new version:
+
+```ruby
+resource :products, actions: [:index, :show, :search]
+
+version 1.1 do
+  resource :sales, actions: [:all]
+  # the products resource is inherited from version 1
+end
+
+version 2 do
+  # the products resource is inherited from version 1.1, except we explicitly
+  # remove the `search` action
+  resource :products
+    remove_action :search
+  end
+end
+```
+
+Versions inherit from their ancestors, so anything not explicitly changed in
+version `2` will be carried over from version `1.1`, which in turn inherits from
+version `1`.
+
+In version `1.1`, we’ve added a new `sales` endpoint. This doesn’t introduce a
+breaking change, as users of version `1.0` can still use it without knowing
+about the `sales` endpoint.
+
+However, in version `2` we *do* introduce a breaking change–namely, that
+products can no longer be searched. Users of versions `1.x` of our API will
+still be able to access the endpoint, but users of version `2` will not.
+
+Usually, changes like these would require the addition of new route namespaces
+and groups of controllers. With Cathode, these are all taken care of for you.
+
+## Goodies on the `index` action
+By default `index` actions return all records in your resource’s default scope.
+However, common operations–like filtering, sorting, pagination, cursoring,
+etc–are also supported. For example, an application might make the following API
+call:
+
+```ruby
+GET /api/products?query=flashlight&sort=desc&page=5
+```
+
+To add support for this functionality in Cathode, just flip on querying, sorting,
+and paging in the `index` action:
+
+```ruby
+resource :products do
+  action :index do
+    allows :querying, :sorting, :paging
+  end
+end
+```
+
+## Params
+All actions have access to the request `params` hash.
+
+## Custom action behavior
+Of course, you won’t want to use Cathode’s default actions in every scenario.
+
+```ruby
+version 2.1 do
+  resource :sales, actions: [:all] do
+    action :show do
+      change 'Checks user permission'
+      access_filter do |current_user|
+        resource.user == current_user
+      end
+    end
+  end
+end
+```
+
+In this case, we need to prevent users from seeing sales that aren’t theirs.
+Happily, Cathode provides some neat shorthands for common scenarios like this.
+`access_filter` can be applied to any action, and should be a method that
+returns `true` if the user can access the resource and `false` if not. If the
+user cannot access the resource, a `401 Unauthorized` header will be sent.
+
+In those cases where you want to do all of the logic yourself, and just want the
+endpoints that Cathode generates, you can override an action entirely:
+
+```ruby
+resource :sales, actions: [:all] do
+  # show a random sale instead
+  override_action :show do
+    render json: Sale.sample
+  end
+end
+```
+
+## Deprecation
+With Cathode’s slick versioning, you’ll be implicitly deprecating junk in previous
+versions each time you introduce a new breaking change. When that happens, users
+of previous versions of your API should be told that a feature they’re using is
+deprecated. By default, Cathode will respond with a deprecation warning for those
+users. So users of version `1.1` of your API would receive the following
+response when making a call to `/api/products/search`:
+
+```json
+{
+  "products": [ array of the products found… ]
+  "messages": [
+    "The search endpoint is deprecated and is removed in version 2.0.0 of the
+API"]
+}
+```
+
+## Files & Naming Conventions
+While this example has been putting all actions in a single file, in reality
+you’ll probably want to specify individual files for each resource. You can use
+the same versioning scheme in those files; as long as your resource APIs inherit
+from `Cathode::API`, Cathode will match up everything accordingly:
+
+```ruby
+# app/api/products_api.rb
+
+class ProductsAPI < Cathode::API
+  actions: [:index, :show, :search] # version 1.0.0 is implied
+
+  version 2 do
+    remove_action :search
+  end
+end
+```
+
+Since nothing about products changed in version 1.2 (which only added sales,
+above), it will use the same actions as it did in version 1. In version 2,
+everything is carried over except for the `search` endpoint.
+
+## Documentation & Changelogs
+By sticking to Cathode’s versioning scheme, you tell it a lot about your API. So
+much, in fact, that we can use it to automatically generate documentation for
+all versions of your API and generate a changelog. Running `cool docs` will
+generate the documentation at `docs/api/1.0.0`, `docs/api/1.1.0`,
+`docs/api/2.0.0`, and `docs/api/2.1.0`. It will also automatically add a
+`Changelog`:
+
+```markdown
+# Changelog
+## Version 2.1.0
+Checks user permission in `sales#show`.
+
+## Version 2.0.0
+Removes the `search` endpoint from `products` resource.
+
+## Version 1.1.0
+Adds `sales` resource with the following endpoints:
+- `GET /api/sales`
+- `GET /api/sales/{id}`
+- `GET /api/sales/search`
+- `POST /api/sales`
+- `PUT /api/sales/{id}`
+- `DELETE /api/sales/{id}`
+
+## Version 1.0.0
+Initial release
+
+Adds `products` resource with the following endpoints:
+- `GET /api/products`
+- `GET /api/products/{id}`
+- `GET /api/products/search`
+- `POST /api/products`
+- `PUT /api/products/{id}`
+- `DELETE /api/products/{id}`
+```
+
+## Related Reading & Projects
+* [Versionist](https://github.com/bploetz/versionist)
+* [Existing Rails API Solutions Suck](http://joshsymonds.com/blog/2013/02/22/existing-rails-api-solutions-suck/])
+* [Grape](https://github.com/intridea/grape)
+* [Roar](https://github.com/apotonick/roar)
+* [Rails API](https://github.com/rails-api/rails-api)

data/Rakefile

@@ -0,0 +1,26 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Cathode'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+task :default => :spec

data/app/assets/javascripts/cathode/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/stylesheets/cathode/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/controllers/cathode/base_controller.rb

@@ -0,0 +1,47 @@
+class Cathode::BaseController < ActionController::Base
+  before_action :process_access_filter
+
+  def index
+    render json: resources.load
+  end
+
+  def create
+    render json: model.create(resource_params)
+  end
+
+  def destroy
+    resource.destroy
+    head :ok
+  end
+
+  def show
+    make_request(request)
+  end
+
+private
+
+  def make_request(http_request)
+    request = Cathode::Request.new(http_request, params)
+    render json: request.body, status: request.status
+  end
+
+  def resources
+    model.all
+  end
+
+  def resource
+    model.find params[:id]
+  end
+
+  def resource_params
+    params[controller_name.singularize]
+  end
+
+  def model
+    controller_name.classify.constantize
+  end
+
+  def process_access_filter
+
+  end
+end

data/app/helpers/cathode/application_helper.rb

@@ -0,0 +1,4 @@
+module Cathode
+  module ApplicationHelper
+  end
+end

data/app/views/layouts/cathode/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Cathode</title>
+  <%= stylesheet_link_tag    "cathode/application", media: "all" %>
+  <%= javascript_include_tag "cathode/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+Cathode::Engine.routes.draw do
+end

data/lib/cathode.rb

@@ -0,0 +1,14 @@
+require 'cathode/engine'
+require 'cathode/base'
+require 'cathode/exceptions'
+
+module Cathode
+  class Engine < ::Rails::Engine
+    config.generators do |g|
+      g.test_framework      :rspec,        :fixture => false
+      g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      g.assets false
+      g.helper false
+    end
+  end
+end

data/lib/cathode/_version.rb

@@ -0,0 +1,3 @@
+module Cathode
+  VERSION = "0.0.1"
+end

data/lib/cathode/action.rb

@@ -0,0 +1,82 @@
+module Cathode
+  class Action
+    attr_reader :action_access_filter,
+                :name,
+                :resource
+
+
+    def self.create(action, resource, &block)
+      klass = case action
+              when :index
+                IndexAction
+              when :show
+                ShowAction
+              when :create
+                CreateAction
+              when :update
+                UpdateAction
+              when :destroy
+                DestroyAction
+              end
+      klass.new(action, resource, &block)
+    end
+
+    def initialize(action, resource, &block)
+      @name, @resource = action, resource
+
+      self.instance_eval &block if block_given?
+    end
+
+    def perform(params)
+      if action_access_filter && !action_access_filter.call
+        return { status: :unauthorized }
+      end
+
+      body = perform_action params
+
+      return { body: body, status: :ok }
+    end
+
+  private
+
+    def model
+      resource.to_s.camelize.singularize.constantize
+    end
+
+    def access_filter(&filter)
+      @action_access_filter = filter
+    end
+  end
+
+  class IndexAction < Action
+    def perform_action(params)
+      model.all
+    end
+  end
+
+  class ShowAction < Action
+    def perform_action(params)
+      model.find params[:id]
+    end
+  end
+
+  class CreateAction < Action
+    def perform_action(params)
+      model.create params
+    end
+  end
+
+  class UpdateAction < Action
+    def perform_action(params)
+      record = model.find(params[:id])
+      record.update params
+      record.reload
+    end
+  end
+
+  class DestroyAction < Action
+    def perform_action(params)
+      model.find(params[:id]).destroy
+    end
+  end
+end