grape_ape_rails 0.5.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20211d0d61dba9ad806f88f8ea9e787d6ae9ac50
-  data.tar.gz: fb3ad6d3d737ce6dcf2881c6d6979e627dc79840
+  metadata.gz: e824e2537351f93db1a3ed5cfdce4ec40b81d0f2
+  data.tar.gz: 1a3e327e2214920119b74e73860de459de9bdc87
 SHA512:
-  metadata.gz: f61b17889217ccd1ae707af14b481039c49638d84d496a3669c9a4125be178a9571e87410203ca0129a394fb87dced1cd81e6b883d46590c6e64ce297dd0261b
-  data.tar.gz: dab69feaac7a11ab08e4b3a65716bebc93bec60f60727317866fbc4e612a8e5cd76b1143ff96fc2815752a67784f30c5cfbc3b87f49c4934ec9695d5af004f4d
+  metadata.gz: cb81cbfa2a74492f1a6dd920c5465ff551a86f2af6d6341fdc770b80d1cdef3ea045320f0f0f6728b7c2ee261dbe7835d07d3ffb12cc5e1aa604a11a35a9e568
+  data.tar.gz: 670bcf477439e38f345e02b574136822087a039d0a2d8e7cbbd3d6e0de3c5969a78a7e4f925975e6434cb59c8e2e2bbf392ea4748ad3e5b2cbd7436fa4b5bc6e

data/README.md

@@ -1,6 +1,32 @@
 # GrapeApeRails
 
-TODO: Write a gem description
+[![Gem Version](https://badge.fury.io/rb/grape_ape_rails.svg)](http://badge.fury.io/rb/grape_ape_rails)
+[![Code Climate](https://codeclimate.com/github/mepatterson/grape_ape_rails/badges/gpa.svg)](https://codeclimate.com/github/mepatterson/grape_ape_rails)
+[![Test Coverage](https://codeclimate.com/github/mepatterson/grape_ape_rails/badges/coverage.svg)](https://codeclimate.com/github/mepatterson/grape_ape_rails)
+[![Build Status](https://semaphoreapp.com/api/v1/projects/dbb9cbd7-0767-4215-b3f8-faa25510b708/231133/shields_badge.png)](https://semaphoreapp.com/mepatterson/grape_ape_rails)
+
+The general purpose of this gem is to wrap the various best practices of integrating GrapeAPI within the context of a Rails app
+into an easy-to-use macro-framework and DSL, plus some opinionated value-adds and features. Basically, Grape and Rails play
+together great, but can be tricky to integrate in a robust, clean way; GrapeApeRails (hopefully) makes your life easier.
+
+## Features/Opinions
+
+GrapeApeRails is opinionated. The goal is to make integration easier, so GrapeApeRails makes a number of integration decisions for you:
+
+* API endpoints respond with JSON
+* API endpoints expect serialized JSON strings for POST and PUT bodies
+* JSON responses are wrapped in a structure that mostly resembles the JSON-RPC spec
+* GrapeApeRails APIs are header-versioned using the 'Accept' HTTP header
+* API endpoints automatically handle locale if provided (either via params[:locale] or the 'Accept-Language' header) and use the `http_accept_language` middleware
+* GrapeApeRails provides an ActiveSupport::Notification that can be suscribed to for logging/injection into the Rails log
+* Pagination support is already included for all endpoints via the [grape-kaminari gem](https://github.com/monterail/grape-kaminari)
+* Rails cache support is already included for all endpoints via the [grape-rails-cache gem](https://github.com/monterail/grape-rails-cache)
+* API endpoints are automagically documented into [Swagger API XML docs](https://helloreverb.com/developers/swagger), presented by your API via mounted endpoints
+* Swagger-documented APIs are automatically separated into different URIs by API version
+
+If these opinions and features align closely to what you're planning to build for your API, I think you'll find GrapeApeRails very useful.
+If you're intending to build something very different from the above, you're probably better off integrating Grape on your own, or looking at alternate projects
+like [Rails::API](https://github.com/rails-api/rails-api).
 
 ## Installation
 
@@ -16,13 +42,239 @@ Or install it yourself as:
 
     $ gem install grape_ape_rails
 
+## Setup
+
+First, GrapeApeRails needs an initializer as `config/initializers/grape_ape_rails.rb`
+
+The easiest way to do this is to run the handy rails generator command:
+
+```ruby
+rails g grape_ape_rails:setup
+```
+
+This will:
+* create your initializer with some default settings, based on how you answer the questions
+* add a `tilt.root` Rack config to your application.rb for use with Rabl templates
+
+Next, you'll need to create your `API::Base` class, which serves as the starting point for all
+of your API endpoints and all versions of your API. By default, GrapeApeRails looks for a
+base.rb file in `app/controllers/api/base.rb`
+
+```ruby
+# app/controllers/api/base.rb
+module API
+  class Base < GrapeApeRails::API
+    grape_apis do
+      api "V1" do
+        # ... mounts go here
+      end
+    end
+  end
+end
+```
+
+NOTE: the api name needs to look like a class name, with camelcase (e.g. "V1" or "AdminV1").
+This actually _is_ the class that GrapeApeRails will then expect you to define for exposing your endpoints.
+Internally, Grape will translate this to an under-dotted version name (e.g "v1" or "admin.v1")
+and this is what will be expected in the Accept header string provided by the requestor.
+
 ## Usage
 
-TODO: Write usage instructions here
+Now that you've got your base.rb ready, you need to mount your various resources/endpoints. This is
+done via the `grape_mount` command. These should generally be mounted as pluralized resource names.
+
+```ruby
+# inside the base.rb ...
+api "V1" do
+  grape_mount :widgets
+  grape_mount :robots
+  grape_mount :pirates
+  # ... etc
+end
+```
+
+If you try to spin up your app now, it will complain that you need to actually create the class files
+for each of the resources you've mounted. So let's do that in a 'v1' subfolder...
+
+```ruby
+# app/controllers/api/v1/widgets.rb
+module API
+  module V1
+    class Widgets < GrapeApeRails::API
+      include GrapeApeRails::Handlers::All
+
+      resource :widgets do
+        desc "Get a single Widget"
+        get ':id', rabl: 'v1/widget' do
+          @widget = Widget.find(params[:id])
+          @widget
+        end
+      end
+    end
+  end
+end
+```
+
+In this case, I've simply created a `/widgets/:id` endpoint, but you can define whatever endpoints you want.
+Because you've defined this within the :widgets resource, the API will assume all of these endpoints begin
+with `/widgets`
+
+### Rabl
+
+In my example, I'm using the default Rabl-based templating. The `rabl` parameter expects a path to the .rabl template file,
+as found within /app/views/api/ ... all Rabl functionality should work as expected.
+
+NOTE: Unlike the ActiveModel Serializers, the Rabl formatter doesn't impose any sort of resource-keyed hash for the response.
+This is your responsibility to define in your Rabl template if you want to use the "plural key, always-array" standard.
+
+Example Rabl templates:
+```ruby
+# v1/base_widget.rabl
+attributes *Widget.column_names
+
+# single widget (v1/widget.rabl)
+collection [@widget] => :widgets
+extends "v1/base_widget"
+
+# array of multiple widgets (v1/widgets.rabl)
+collection @widgets => :widgets
+extends "v1/base_widget"
+```
+
+### ActiveModel Serializers
+
+If you'd prefer ActiveModel Serializers over Rabl, GrapeApeRails supports that as well via a custom Grape formatter
+called `Grape::Formatter::GarActiveModelSerializers`. To use it, just override the `formatter` within each of your API
+classes.
+
+```ruby
+module API
+  module V1
+    class Monkeys < GrapeApeRails::API
+      include GrapeApeRails::Handlers::All
+
+      formatter :json, Grape::Formatter::GarActiveModelSerializers
+
+      resource :monkeys do
+        desc "Get a single Monkey"
+        get ':id' do
+          @monkey = Monkey.find(params[:id])
+          @monkey
+        end
+      end
+    end
+  end
+end
+```
+
+In this case, it's expected that you've defined a MonkeySerializer class in your models directory, as usual with ActiveModelSerializers.
+
+IMPORTANT: For ActiveModel Serializers, when defining the response structure, I made the decision (based on lots of research) to go with a plural resource key and an _always-array_ approach in the
+response hash. To put it another way:
+
+If you ask for /widgets/1 you will get
+
+`{ "result" : { "widgets" : [ {<widget>} ] } }`
+
+and if you ask for /widgets you will get
+
+`{ "result" : { "widgets" : [ {widget1}, {widget2}, {widget3}, ... ] } }`
+
+#### Overriding the ActiveModel Serializer resource key
+
+If you need, for some reason, to provide a different key in your response hash, you can
+override the resource key for the plural form of your resource.
+
+Let's say, for example, that you've created a `UserSerializer` but you want the JSON to use 'people'...
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :name, :age, :hair_color
+
+  def resource_plural
+    'people'
+  end
+end
+```
+
+... GrapeApeRails will now always key the hash with `"people" : [...one or more people hashes...]` for both single (1-element array) and multiple (n-element array) records.
+
+### JSON Response Structures
+
+Similar to the JSON-RPC spec, endpoints exposed using GrapeApeRails will present either a `result` hash or an `error` hash.
+The error hash will be composed of a `code` (a machine-friendly enum-like uppercase string) and a
+message (human-friendly, user-presentable message that includes the code inside brackets).
+
+```ruby
+# Successful response
+{
+  "result" : {
+    "widgets" : [
+      { "id" : 1, "name" : "Fancy Widget" },
+      { "id" : 2, "name" : "Other Thing" },
+      ...
+    ]
+  }
+}
+
+# Error response
+{
+  "error" : {
+    "code" : "UNAUTHORIZED",
+    "message" : "[UNAUTHORIZED] Requires a valid user authorization"
+  }
+}
+```
+
+In the case of a validation error on a resource, there will additionally be a `data` key inside the error hash that includes Rails-style validation errors.
+
+### Pagination
+
+GrapeApeRails uses Kaminari for pagination via the [grape-kaminari](https://github.com/monterail/grape-kaminari) gem.
+
+Enabling pagination on a resource is super-simple:
+
+```ruby
+# inside your API resource class...
+desc "Return a list of Widgets"
+params :pagination do
+  optional :page,     type: Integer
+  optional :per_page, type: Integer
+  optional :offset,   type: Integer
+end
+paginate per_page: 30
+get '/', rabl: 'v1/widgets' do
+  @widgets = paginate(@widgets)
+end
+```
+
+_From the grape-kaminari docs:_
+
+Now you can make a HTTP request to your endpoint with the following parameters
+
+- `page`: your current page (default: 1)
+- `per_page`: how many to record in a page (default: 10)
+- `offset`: the offset to start from (default: 0)
+
+```
+curl -v http://host.dev/widgets?page=3&offset=10
+```
+
+and the response will be paginated and also will include pagination headers
+
+```
+X-Total: 42
+X-Total-Pages: 5
+X-Page: 3
+X-Per-Page: 10
+X-Next-Page: 4
+X-Prev-Page: 2
+X-Offset: 10
+```
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/grape_ape_rails/fork )
+1. Fork it
 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/grape_ape_rails.gemspec

@@ -43,4 +43,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'timecop'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'webmock'
+  spec.add_development_dependency 'codeclimate-test-reporter'
 end

data/lib/grape_ape_rails/api.rb

@@ -42,17 +42,10 @@ module GrapeApeRails
       @gar_api_version = name
       mounts_klass = Class.new(GrapeApeRails::API)
       klass = GrapeApeRails.const_set("#{name}Base", mounts_klass)
-      api_key = GrapeApeRails.configuration.api_secret_key
-      api_key = args[0] if args[0].present? && args[0].is_a?(String)
-
+      api_key = api_key_from(args)
       api_version = name.underscore.gsub('_','.')
-      if args[0].present? && args[0].is_a?(Array)
-        GrapeApeRails::API.api_version_cascades_map.merge!({ api_version => args[0].map{ |v| v.underscore.gsub('_','.') } })
-      elsif args[1].present? && args[1].is_a?(Array)
-        GrapeApeRails::API.api_version_cascades_map.merge!({ api_version => args[1].map{ |v| v.underscore.gsub('_','.') } })
-      end
-      dotname = name.underscore.gsub('_','.')
-      GrapeApeRails::API.api_keys_map.merge!({ dotname => api_key })
+      update_api_version_cascades_map(api_version, args)
+      update_api_keys_map(name, api_key)
       yield
       mount mounts_klass
     ensure
@@ -72,6 +65,32 @@ module GrapeApeRails
       puts "    [ERROR] Could not instantiate API Endpoints at '#{name}'. Maybe you still need to create the class file?"
     end
 
+    private
+
+    class << self
+      def api_key_from(args)
+        api_key = GrapeApeRails.configuration.api_secret_key
+        api_key = args[0] if args[0].present? && args[0].is_a?(String)
+        api_key
+      end
+
+      def update_api_keys_map(name, api_key)
+        GrapeApeRails::API.api_keys_map.merge!({ name.underscore.gsub('_','.') => api_key })
+      end
+
+      def update_api_version_cascades_map(api_version, args)
+        return unless arr = cascades_array_from(args)
+        cascades = arr.map{ |v| v.underscore.gsub('_','.') }
+        GrapeApeRails::API.api_version_cascades_map.merge!({ api_version => cascades })
+      end
+
+      def cascades_array_from(args)
+        return args[0] if args[0].present? && args[0].is_a?(Array)
+        return args[1] if args[1].present? && args[1].is_a?(Array)
+        return nil
+      end
+    end
+
   end
 end
 

data/lib/grape_ape_rails/handlers/formatters.rb

@@ -34,10 +34,17 @@ module Grape
     module GarActiveModelSerializers
       def self.call(resource, env)
         if serializer = Grape::Formatter::ActiveModelSerializers.fetch_serializer(resource, env)
-          single = serializer.try(:resource_singular) || serializer.object.class.name.underscore
-          plural = serializer.try(:resource_plural) || serializer.object.class.name.underscore.pluralize
-          hash = serializer.as_json
-          output = if hash[single].present?
+          # single = serializer.try(:resource_singular) || serializer.object.class.name.underscore
+          # default_plural = default_plural = serializer.object.class.name.underscore.pluralize
+          # if serializer.object.is_a?(Array)
+            # single = serializer.object.first.class.name.underscore
+            # default_plural = serializer.object.first.class.name.underscore.pluralize
+          # end
+          # plural = serializer.try(:resource_plural) || default_plural
+          single = serializer.try(:resource_singular) || serializer.instance_variable_get(:@resource_name).try(:singularize) || serializer.instance_variable_get(:@object).class.name.underscore
+          plural = serializer.try(:resource_plural) || serializer.instance_variable_get(:@resource_name) || single.pluralize
+          hash = serializer.as_json(root: false)
+          output = if hash.is_a?(Hash) && hash[single].present?
             hash[single].is_a?(Array) ? hash[single] : [hash[single]]
           else
             hash.is_a?(Array) ? hash : [hash]
@@ -77,14 +84,11 @@ module Grape
         private
 
         def wrap_output(output)
-          # root_resource = endpoint.route.route_namespace.gsub('/','').pluralize
           template = MultiJson.dump({ result: "***" })
-          # output = "[#{output}]" if output[0] != '[' && output[-1] != ']'
           template.gsub(%Q("***"), output)
         end
 
         def view_path(template)
-          # api_version = endpoint.route.route_version || '.'
           if template.split('.')[-1] == 'rabl'
             File.join(env['api.tilt.root'], template)
           else

data/lib/grape_ape_rails/version.rb

@@ -1,3 +1,3 @@
 module GrapeApeRails
-  VERSION = "0.5.1"
+  VERSION = "0.9.1"
 end

data/spec/dummy/app/controllers/api/v1/widgets.rb

@@ -3,6 +3,10 @@ module API
     class Widgets < GrapeApeRails::API
       include GrapeApeRails::Handlers::All
 
+      get "/thing" do
+        { foo: 42 }
+      end
+
       resource :widgets do
         desc "Get a single Widget"
         get ':id', rabl: 'v1/widget' do

data/spec/requests/v1/widgets_spec.rb

@@ -9,6 +9,14 @@ describe API::V1::Widgets do
     end
   end
 
+  describe 'GET /thing' do
+    it "returns the expected json hash for a non-resource endpoint" do
+      req :get, "/thing"
+      json = MultiJson.load(response.body, symbolize_keys: true)
+      expect(json).to eql({ result: { foo: 42 } })
+    end
+  end
+
   describe "GET /widgets/:id/:name" do
     let(:widget) { FactoryGirl.create(:widget) }
 

data/spec/spec_helper.rb

@@ -1,3 +1,5 @@
+require "codeclimate-test-reporter"
+CodeClimate::TestReporter.start
 ENV["RAILS_ENV"] = "test"
 
 require File.expand_path("../dummy/config/environment.rb",  __FILE__)
@@ -9,7 +11,7 @@ require 'factory_girl'
 require 'timecop'
 require 'pry'
 require 'webmock/rspec'
-WebMock.disable_net_connect!(allow_localhost: true)
+WebMock.disable_net_connect!(allow_localhost: true, allow: "codeclimate.com")
 
 Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape_ape_rails
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.9.1
 platform: ruby
 authors:
 - Matt E. Patterson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-16 00:00:00.000000000 Z
+date: 2015-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -346,6 +346,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides customized Grape API functionality inside Rails
 email:
 - madraziel@gmail.com