jsend_wrapper-rails 0.1.0

data/README.md

@@ -0,0 +1,306 @@
+# Rails JSend Wrapper
+
+## Usage
+
+Add the following lines to your Gemfile:
+
+```ruby
+gem 'jsend_wrapper-rails'
+gem 'jbuilder' # optional
+```
+
+### render jsend: ...
+
+```ruby
+# Success
+render jsend: @object
+render jsend: { success: @object }
+
+# Fail
+render jsend: { fail: 'too bad' }
+
+# Error
+render jsend: { error: 'too bad' }
+render jsend: { error: 'too bad', code: 123 }
+render jsend: { error: 'too bad', data: @object }
+render jsend: { error: 'too bad', code: 123, data: @object }
+```
+
+The elements `code` and `data` are optional for JSend Error containers. If you
+leave them out, they will be absent from the rendered JSON. Note the differences
+in these two examples:
+
+`render jsend: {error: 'too bad'}`
+
+**Result**:
+```json
+{
+  "status": "error",
+  "message": "too bad"
+}
+```
+
+`render jsend: {error: 'too bad', data: nil}`
+
+**Result**:
+```json
+{
+  "status": "error",
+  "message": "too bad",
+  "data": null
+}
+```
+
+
+### Templates (optional)
+
+If [JBuilder](https://rubygems.org/gems/jbuilder) is available, you can create
+view files with a `.jsend` (example: `app/views/posts/show.json.jsend`)
+extension. These views are rendered by `Jbuilder`, exactly as if they were
+named with a `.jbuilder` extension instead. These views will be wrapped in a
+JSend Success container.
+
+**Example**: `app/views/posts/show.json.jsend`
+```ruby
+json.title 'The Pragmatic Programmer'
+json.year  1999
+```
+
+**Result**:
+```json
+{
+  "status": "success",
+  "data": {
+    "title": "The Pragmatic Programmer",
+    "year": 1999
+  }
+}
+```
+
+### Tips
+
+#### Handling Errors
+
+You can use `rescue_from` to automatically handle errors: 
+
+```ruby
+rescue_from ActiveRecord::RecordNotFound do
+  render status: :not_found, jsend: {
+    error: 'record not found', code: 404, data: { id: params[:id] } }
+end
+```
+
+**Example**: `GET /posts/1234.json`:
+```json
+{
+  "status": "error",
+  "message": "record not found",
+  "code": 404,
+  "data": {
+    "id": "1234"
+  }
+}
+```
+
+## JSend Spec
+
+ * **What?** - Put simply, JSend is a specification that lays down some rules
+   for how [JSON](http://json.org) responses from web servers should be
+   formatted. JSend focuses on application-level (as opposed to protocol- or
+   transport-level) messaging which makes it ideal for use in
+   [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer)-style
+   applications and APIs.
+ * **Why?** - There are lots of web services out there providing JSON data,
+   and each has its own way of formatting responses.  Also, developers writing
+   for JavaScript front-ends continually re-invent the wheel on communicating
+   data from their servers.  While there are many common patterns for
+   structuring this data, there is no consistency in things like naming or types
+   of responses.  Also, this helps promote happiness and unity between backend
+   developers and frontend designers, as everyone can come to expect a common
+   approach to interacting with one another.
+ * **Hold on now, aren't there already specs for this kind of thing?** - 
+   Well... no.  While there are a few handy specifications for dealing with JSON
+   data, most notably [Douglas Crockford](http://www.crockford.com/)'s
+   [JSONRequest](http://www.json.org/JSONRequest.html) proposal, there's nothing
+   to address the problems of general application-level messaging.  More on this
+   later.
+ * **(Why) Should I care?** - If you're a library or framework developer, this
+   gives you a consistent format which your users are more likely to already be
+   familiar with, which means they'll already know how to consume and interact
+   with your code.  If you're a web app developer, you won't have to think about
+   how to structure the JSON data in your application, and you'll have existing
+   reference implementations to get you up and running quickly.
+ * **Discuss** - [Mailing list](http://lists.omniti.com/mailman/listinfo/jsend-users)
+
+### So how's it work?
+
+A basic JSend-compliant response is as simple as this:
+```json
+{
+  "status": "success",
+  "data": {
+    "post": {
+      "id": 1,
+      "title": "A blog post",
+      "body": "Some useful content"
+     }
+  }
+}
+```
+
+When setting up a JSON API, you'll have all kinds of different types of calls
+and responses.  JSend separates responses into some basic types, and defines
+required and optional keys for each type:
+
+<table>
+  <thead>
+    <tr>
+      <th>Type</th>
+      <th>Description</th>
+      <th>Required Keys</th>
+      <th>Optional Keys</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>success</td>
+      <td>All went well, and (usually) some data was returned.</td>
+      <td>status, data</td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>fail</td>
+      <td>
+        There was a problem with the data submitted, or some pre-condition of 
+        the API call wasn't satisfied.
+      </td>
+      <td>status, message</td>
+      <td></td>
+    </tr>
+    <tr>
+      <td>error</td>
+      <td>
+        An error occurred in processing the request, i.e. an exception was 
+        thrown.
+      </td>
+      <td>status, message</td>
+      <td>code, data</td>
+    </tr>
+  </tbody>
+</table>
+
+### Example response types
+
+**Success**: When an API call is successful, the JSend object is used as a
+simple envelope for the results, using the {{{data}}} key, as in the following:
+
+**`GET /posts.json`:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "id": 1,
+      "title": "A blog post",
+      "body": "Some useful content"
+    },
+    {
+      "id": 2,
+      "title": "Another blog post",
+      "body": "More content"
+    },
+  ]
+}
+```
+
+**`GET /posts/2.json`:**
+```json
+{
+  "status": "success",
+  "data": {
+    "id": 2,
+    "title": "Another blog post", 
+    "body": "More content"
+  }
+}
+```
+
+**`DELETE /posts/2.json`:**
+```json
+{
+  "status": "success",
+  "data": null
+}
+```
+
+Required keys:
+ * status: Should always be set to "success".
+ * data: Acts as the wrapper for any data returned by the API call.  If the call
+   returns no data (as in the last example), data should be set to null.
+
+**Fail**: When an API call is rejected due to invalid data or call conditions,
+the JSend object's data key contains an object explaining what went wrong,
+typically a hash of validation errors.  For example:
+
+**`POST /posts.json`** (with data `body: "Trying to creating a blog post"`):
+```json
+{
+  "status": "fail",
+  "data": {
+    "title": "A title is required"
+  }
+}
+```
+
+Required keys:
+ * status: Should always be set to "fail".
+ * data: Again, provides the wrapper for the details of why the request failed.
+   If the reasons for failure correspond to `POST` values, the response
+   object's keys *should* correspond to those `POST` values.
+
+**Error**: When an API call fails due to an error on the server.  For example:
+
+**`GET /posts.json`**:
+```json
+{
+    "status" : "error",
+    "message" : "A title is required"
+}
+```
+
+Required keys:
+ * status: Should always be set to "error".
+ * message: A meaningful, end-user-readable (or at the least log-worthy)
+   message, explaining what went wrong.
+
+Optional keys:
+ * code: A numeric code corresponding to the error, if applicable
+ * data: A generic container for any other information about the error, i.e. the
+   conditions that caused the error, stack traces, etc.
+ 
+### Whither HTTP?
+
+But wait, you ask, doesn't HTTP already provide a way to communicate response
+statuses?  Why yes, astute reader, it does.  So how does the notion of
+indicating response status in the message body fit within the context of HTTP?
+Two things:
+ * The official HTTP spec has 41 status codes, and there are many
+   interpretations on how to use each one.  JSend, on the other hand, defines a
+   more constrained set of status codes, specifically related to handling JSON
+   traffic in the context of a dynamic web UI.
+ * The spec is meant to be as small, constrained, and generally-applicable as
+   possible.  As such, it has to be somewhat self-contained.  A common pattern
+   for implementing JSON services is to load a JavaScript file which passes a
+   JSON block into a user-specified callback.  JSON-over-XHR handling in many
+   JavaScript frameworks follows similar patterns.  As such, the end-user
+   (developer) never has a chance to access the HTTP response itself.
+
+So where does that leave us?  Accounting for deficiencies in the status quo does
+not negate the usefulness of HTTP compliance.  Therefore it is advised that
+server-side developers use both: provide a JSend response body, and whatever
+HTTP header(s) are most appropriate to the corresponding body.
+
+### License
+
+The JSend specification (this page) is covered under a
+[License modified BSD License](http://labs.omniti.com/labs/jsend/wiki/License)

data/Rakefile

@@ -0,0 +1,65 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'jeweler'
+
+require_relative 'lib/jsend_wrapper/version'
+
+begin
+  Bundler.setup :default, :development
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+
+Jeweler::Tasks.new do |gem|
+  gem.name = 'jsend_wrapper-rails'
+  gem.version = JsendWrapper::Version.to_s
+  gem.homepage = 'http://github.com/sangster/jsend_wrapper-rails'
+  gem.license = 'GPL 3'
+  gem.summary = 'Wraps JSON in a JSend envelope'
+  gem.description = <<-EOF.strip.gsub /\s+/, ' '
+    Some description here.
+  EOF
+  gem.email = 'jon@ertt.ca'
+  gem.authors = ['Jon Sangster']
+
+  gem.files = Dir['{lib}/**/*', 'Rakefile', 'README.md', 'LICENSE']
+  gem.files.exclude 'lib/jsend_wrapper/version.rb'
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+task :pry do
+  exec 'pry --gem'
+end
+
+task bump: ['bump:patch']
+namespace :bump do
+  [:major, :minor, :patch].each do |part|
+    bumper = JsendWrapper::Version::Bumper.new part
+    desc "Bump the version to #{bumper}"
+    task(part) { bumper.bump }
+  end
+end
+
+# RSpec
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new :spec
+task default: :spec

data/lib/jsend_wrapper/rails/railtie.rb

@@ -0,0 +1,58 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+require 'rails/railtie'
+
+module JsendWrapper
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer 'jsend_wrapper-rails.initialization' do
+        if JsendWrapper::Rails.jbuilder_available?
+          JsendWrapper::Rails.install_template
+        end
+        JsendWrapper::Rails.install_render_option
+      end
+    end
+
+
+    #@return [Boolean] true if the {Jbuilder} gem is available
+    def self.jbuilder_available?
+      require 'jbuilder'
+      true
+    rescue LoadError
+      STDERR.puts 'WARN: Please include the "jbuilder" gem for .jsend templates'
+      false
+    end
+
+    # Install a "template handler" for .jsend view files. These files will be
+    # processed with {Jbuilder}, just like .jbuilder view files, but the result
+    # will be wrapped in a "success" JSend wrapper.
+    def self.install_template
+      ActionView::Template.register_template_handler \
+        :jsend, JsendWrapper::Rails::TemplateHandler
+    end
+
+
+    # Adds the "jsend:" option to {ActiveController::Base#render}
+    def self.install_render_option
+      require_relative 'render_option'
+
+      ActionController::Renderers.add :jsend do |value, _|
+        self.content_type ||= Mime::JSON
+        RenderOption.new(value).render
+      end
+    end
+  end
+end

data/lib/jsend_wrapper/rails/render_option.rb

@@ -0,0 +1,76 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+require_relative '../renderers'
+
+module JsendWrapper
+  # Parses the "render jsend: {...}" command. Valid forms:
+  class RenderOption
+    VALID_TYPES   = [:success, :fail, :error]
+    VALID_OPTIONS = [:data, :code, :message]
+    VALID_KEYS    = VALID_TYPES + VALID_OPTIONS
+
+    #@param obj [Hash,Object] Examples:
+    # render jsend: @object
+    # render jsend: {success: @object}
+    # render jsend: {fail: @object}
+    # render jsend: {error: @object}
+    # render jsend: {error: @object, code: 123}
+    # render jsend: {error: @object, data: @another_object}
+    # render jsend: {error: @object, code: 123, data: @another_object}
+    def initialize(obj)
+      @hash = normalize obj
+    end
+
+
+    #@return [String] A string containing the rendered JSON
+    def render
+      renderer.call
+    end
+
+
+    #@return [Renderer] One of {SuccessRenderer}, {FailRenderer}, or
+    #  {ErrorRenderer}
+    def renderer
+      @renderer ||=
+        if @hash.key? :success
+          SuccessRenderer.new @hash[:success]
+        elsif @hash.key? :fail
+          FailRenderer.new @hash[:fail]
+        elsif @hash.key? :error
+          ErrorRenderer.new @hash[:error], @hash.slice(:code, :data)
+        else
+          raise 'render jsend:{...} must include "success:", "fail:", or "error:"'
+        end
+    end
+
+
+private
+
+
+    def normalize(obj)
+      if Hash === obj && jsend_hash?(obj)
+        obj
+      else
+        {success: obj}
+      end
+    end
+
+
+    def jsend_hash?(hash)
+      hash.keys.all? { |key| VALID_KEYS.include? key }
+    end
+  end
+end

data/lib/jsend_wrapper/rails/template_handler.rb

@@ -0,0 +1,43 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+module JsendWrapper
+  module Rails
+    class TemplateHandler
+      def self.call(template)
+        json_handler = ActionView::Template.registered_template_handler :jbuilder
+        json = json_handler.call template
+
+        <<-RUBY
+          content = instance_eval #{json.inspect}
+          JsendWrapper::Handlers::Success.new(self).render content
+        RUBY
+      end
+
+
+      #@param view [ActiveView::Base]
+      def initialize(view)
+        @view = view
+      end
+
+
+      #@param json [String]
+      def render(json, *)
+        json = 'null' if !json || json.empty?
+        %[{"status":"success","data":#{json}}]
+      end
+    end
+  end
+end

data/lib/jsend_wrapper/renderers/error_renderer.rb

@@ -0,0 +1,67 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+require_relative 'renderer'
+
+module JsendWrapper
+  # Wraps the given message in a JSend Error. JSend Errors have two required
+  # elements (status, message) and two optional elements (code, data).
+  class ErrorRenderer < Renderer
+    attr_accessor :message, :has_code, :code, :has_data, :data
+
+    alias_method :code?, :has_code
+    alias_method :data?, :has_data
+
+    #@param message [#to_s]
+    #@param optional [Hash] the optional elements
+    #@option optional [#to_i] :code a numeric code representing the error
+    #@option optional [Object] :data a generic container for any other
+    #  information about the error
+    def initialize(message, optional)
+      self.message  = message.to_s
+      self.has_code = optional.key? :code
+      self.has_data = optional.key? :data
+
+      self.code = parse_code optional[:code] if code?
+      self.data = optional[:data]            if data?
+    end
+
+
+    #@return [String] the rendered JSON
+    def call
+      %[{"status":"error","message":#{message.to_json}#{optional}}]
+    end
+
+
+  private
+
+
+    def parse_code(code)
+      if code.respond_to? :to_i
+        code.to_i
+      else
+        raise '"code" must respond to #to_i'
+      end
+    end
+
+
+    def optional
+      ''.tap do |json|
+        json << ',"code":' << code.to_s         if code?
+        json << ',"data":' << json_string(data) if data?
+      end
+    end
+  end
+end

data/lib/jsend_wrapper/renderers/fail_renderer.rb

@@ -0,0 +1,32 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+require_relative 'renderer'
+
+module JsendWrapper
+  # Wraps the given message in a JSend Failure. JSend Failures have two required
+  # elements (status, data).
+  class FailRenderer < Renderer
+    attr_accessor :data
+
+    def initialize(obj)
+      self.data = obj
+    end
+
+    def call
+      %[{"status":"fail","data":#{json_string data}}]
+    end
+  end
+end

data/lib/jsend_wrapper/renderers/renderer.rb

@@ -0,0 +1,30 @@
+# jsend_wrapper-rails: Wrap JSON views in JSend containers
+# Copyright (C) 2014 Jon Sangster
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+module JsendWrapper
+  class Renderer
+  protected
+
+    def json_string(obj)
+      if obj.respond_to? :to_json
+        obj.to_json
+      elsif obj.nil?
+        'null'
+      else
+        obj.to_s.to_json
+      end
+    end
+  end
+end