sliver-rails 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f7c14d480287cbdc9a25447e5ceb56f4afb27fb9
-  data.tar.gz: bd5d0f5640681685401e4530b25159139d8eb45f
+  metadata.gz: c3bc921a9806786fed1b48aa7721a6237c2c398e
+  data.tar.gz: 299172b1437ea180c5448ba28a911394e99e2a82
 SHA512:
-  metadata.gz: c856f578505b93d71e73e6c45733414d71f1c382be0e5cb13fdb8e908ed6c2ffb7292dacab3a5d70870add10706b3821a9ec91c099a1abd35781e8c04fcdf5c5
-  data.tar.gz: 15ae1661f31276d01692fda474dc30e05fca889e66603997943aab4ff5c1510765a45deeea461425e48ba382fc6b0b609be391e1753cdbc69c5b9a4464488dcf
+  metadata.gz: 845f43b7b7a51de4175e65e401027bcd99868fd4b7d4d4ac07674e7230f02ab8df999913e5cff24509746306b937b7430e80533b185653291dfa55f583ff3527
+  data.tar.gz: 53455f2c9b07af35a587433408101cd4c7d629d51abc069912ee2572075f1456bd00aa522d55fcae131a8f289a9abd71da9fa1891298fe74ea865d9a85b01b8c

data/README.md

@@ -1,30 +1,150 @@
-# Sliver::Rails
+# Sliver-Rails
 
-TODO: Write a gem description
+Rails-focused extensions to the [Sliver](https://github.com/pat/sliver) API libary.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add the gem to your Gemfile:
 
 ```ruby
-gem 'sliver-rails'
+gem 'sliver-rails', '~> 0.2.0'
 ```
 
-And then execute:
+## Usage
 
-    $ bundle
+Slightly different to the pure Sliver approach, instead of including the `Sliver::Action` module, you should instead inherit from `Sliver::Rails::Action`.
 
-Or install it yourself as:
+```ruby
+app = Sliver::API.new do |api|
+  api.connect :get, '/changes/:id', ChangeAction
+end
 
-    $ gem install sliver-rails
+class ChangeAction < Sliver::Rails::Action
+  def call
+    change = Change.find path_params['id']
 
-## Usage
+    response.status = 200
+    response.body   = ["Change: #{change.name}"]
+  end
+end
+```
+
+### Parameters
+
+Just like in Rails controllers, all incoming request parameters are treated as strong parameters, so you can be explicit about what you're expecting to receive.
+
+```ruby
+class V1::Changes::Create < Sliver::Rails::Action
+  def call
+    change = Change.create change_params
+
+    response.status = 200
+    response.body   = ["Success"]
+  end
+
+  private
+
+  def change_params
+    params.fetch(:change, {}).permit(:name, :description)
+  end
+end
+```
+
+### JSON Requests
+
+If the content-type of the request has been set to `application/json`, then the request body data sent through in POST and PUT requests is parsed and available via the `params` method.
+
+### Inbuilt JSON Processor
+
+Most modern APIs will return JSON-formatted data - and so a Sliver Processor is provided to automatically translate response bodies into JSON. So, in the example below, the response body will be transformed to `"{\"status\":\"OK\"}"`, and the Content-Type header will be set to `application/json`.
+
+```ruby
+class V1::Changes::Create < Sliver::Rails::Action
+  def self.processors
+    [Sliver::Rails::Processors::JSONProcessor]
+  end
+
+  def call
+    change = Change.create change_params
+
+    response.status = 200
+    response.body   = {:status => "OK"}
+  end
+
+  private
+
+  def change_params
+    params.fetch(:change, {}).permit(:name, :description)
+  end
+end
+```
 
-TODO: Write usage instructions here
+### JSON templates and exposed variables
+
+The JSON Processor can also use a Jbuilder template (provided you've got the `jbuilder` gem in your Gemfile) via the `use_template` method. Similarly to [decent_exposure](https://github.com/voxdolo/decent_exposure) (although without most of the features), anything specified with a `expose` call is available in the template view.
+
+```ruby
+class V1::Changes::Create < Sliver::Rails::Action
+  # This will use app/views/api/changes/show.jbuilder
+  use_template 'api/changes/show'
+
+  expose(:change) { Change.new change_params }
+
+  def self.processors
+    [Sliver::Rails::Processors::JSONProcessor]
+  end
+
+  def call
+    response.status = 200 if change.save
+
+    # If you use response.body, the template will not be used.
+    # response.body = {:status => 'OK'}
+  end
+
+  private
+
+  def change_params
+    params.fetch(:change, {}).permit(:name, :description)
+  end
+end
+
+# app/views/api/changes/show.jbuilder
+json.(change, :name, :description)
+```
+
+This is a very simple example, but your Jbuilder templates can be as complex as you like. Blocks provided for `expose` will only be evaluated once and remembered - and if no block is provided, it looks for a private method of the same name (which is also only evaluated once when referenced from the template).
+
+The default template is an instance of `Sliver::Rails::JBuilderTemplate`, which has one method available beyond what you've exposed: `routes`, which provides access to your Rails route helper methods. No other Rails helper methods are provided by default, but you can use your own template if you'd like:
+
+```ruby
+# config/initializers/sliver.rb
+class ApiTemplate
+  include ActionView::Helpers::NumberHelper
+
+  def routes
+    Rails.application.routes
+  end
+end
+
+Rails.application.config.after_initialize do
+  Sliver::Rails.template_class = ApiTemplate
+end
+```
+
+### Common directory and file structures
+
+This is not enforced by this gem, but it's a habit we at [Inspire9](http://inspire9dev.com) have fallen into:
+
+* Separate APIs for separate versions.
+* `app/apis/v1.rb` contains the API definition
+* `app/apis/v1/posts/create.rb`, `app/apis/v1/posts/show.rb`, `app/apis/v1/posts/index.rb` and so forth covering CRUD behaviour for resources.
+* All endpoint classes inherit from an app-specific base class (covering things like `current_user`, setting guards and processors), and that base class inherits from `Sliver::Rails::Action`.
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/sliver-rails/fork )
+Please note that this project now has a [Contributor Code of Conduct](http://contributor-covenant.org/version/1/0/0/). By participating in this project you agree to abide by its terms.
+
+1. Fork it ( https://github.com/pat/sliver-rails/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/sliver/rails/jbuilder_template.rb

@@ -1,5 +1,5 @@
 class Sliver::Rails::JBuilderTemplate
   def routes
-    Rails.application.routes
+    Rails.application.routes.url_helpers
   end
 end

data/sliver-rails.gemspec

@@ -1,7 +1,7 @@
 # coding: utf-8
 Gem::Specification.new do |spec|
   spec.name          = 'sliver-rails'
-  spec.version       = '0.1.1'
+  spec.version       = '0.2.0'
   spec.authors       = ['Pat Allan']
   spec.email         = ['pat@freelancing-gods.com']
   spec.summary       = %q{Rails extensions for Sliver}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sliver-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Pat Allan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-02 00:00:00.000000000 Z
+date: 2015-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sliver