openstax_api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e65fff56b84dbf775bc833cac2d8c0d47ac17071
+  data.tar.gz: 50a0a75083a94728f96ae03850976d69591cfa3c
+SHA512:
+  metadata.gz: 1ee105cdac7c958f73f350386dffad9440b7de73a860f607a5c7df4ef06aec8cfb113a974db0c5e894cc09a2e687f3c66dac4881e25c684b008dc1bd679bee67
+  data.tar.gz: d4e10fbe22973ad8d80143ccbf7e6013064ca6ec9f6792d2612043994fa1521f028c61e38e54db80269d7df9f730efaa4c019979678a4e904539ecd0b1ddab9b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 YOURNAME
+
+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,73 @@
+# openstax_api
+
+API utilities for OpenStax products and tools.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```rb
+gem 'openstax_api'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+## Included classes
+
+This gem includes the following classes, all under the OpenStax::Api namespace:
+
+### Controllers
+
+`ApiController`
+
+`OauthBasedApiController`
+
+Your API controllers should inherit from those classes.
+
+### Models
+
+`ApiUser`
+
+This is the class of someone using the API, which can either be a (signed in) user, a doorkeeper application, or a combination of both.
+
+## Doorkeeper Extensions
+
+This gem also adds the following methods to Doorkeeper::Application:
+
+`is_human?`, `is_application?` and `is_admin?`
+
+## Route simplification
+
+Finally, this gem allows API routes to be simplified by using the api method, like so:
+
+```rb
+apipie
+
+get 'api', to: 'static_pages#api'
+
+api :v1, true do
+  get '/your_api_routes_go_here'
+end
+```
+
+The api route method takes a version argument and a boolean.
+If the boolean is true, that version is the default (latest) and will always match the Accept header. It should be defined last, as any API route after that will be ignored.
+
+## Testing
+
+From the gem's main folder, run `bundle`, and then `rake` to run all the specs.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Create specs for your feature
+4. Ensure that all specs pass
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new pull request
+

data/Rakefile

@@ -0,0 +1,22 @@
+#!/usr/bin/env rake
+# http://viget.com/extend/rails-engine-testing-with-rspec-capybara-and-factorygirl
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+
+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/controllers/openstax/api/v1/api_controller.rb

@@ -0,0 +1,75 @@
+require 'roar-rails'
+
+module OpenStax
+  module Api
+    module V1
+
+      class ApiController < ::ApplicationController
+        
+        include Roar::Rails::ControllerAdditions
+
+        fine_print_skip_signatures(:general_terms_of_use,
+                                   :privacy_policy) \
+          if respond_to? :fine_print_skip_signatures
+
+        skip_protect_beta if respond_to? :skip_protect_beta
+
+        skip_before_filter :authenticate_user!
+
+        respond_to :json
+        rescue_from Exception, :with => :rescue_from_exception
+
+        def self.api_example(options={})
+          return if Rails.env.test?
+          raise IllegalArgument, "must supply a :url parameter" if !options[:url_base]
+
+          url_base = options[:url_base].is_a?(Symbol) ?
+                       UrlGenerator.new.send(options[:url_base], protocol: 'https') :
+                       options[:url_base].to_s
+          
+          "#{url_base}/#{options[:url_end] || ''}"
+        end
+
+        def self.json_schema(representer, options={})
+          RepresentableSchemaPrinter.json(representer, options)
+        end
+        
+      protected
+
+        def rescue_from_exception(exception)
+          # See https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L453 for error names/symbols
+          error = :internal_server_error
+          notify = true
+      
+          case exception
+          when SecurityTransgression
+            error = :forbidden
+            notify = false
+          when ActiveRecord::RecordNotFound, 
+               ActionController::RoutingError,
+               ActionController::UnknownController,
+               AbstractController::ActionNotFound
+            error = :not_found
+            notify = false
+          end
+
+          if notify
+# Not yet in OSU
+=begin
+            ExceptionNotifier.notify_exception(
+              exception,
+              env: request.env,
+              data: { message: "An exception occurred" }
+            )
+=end
+            Rails.logger.error("An exception occurred: #{exception.message}\n\n#{exception.backtrace.join("\n")}") \
+          end
+          
+          head error
+        end
+
+      end
+
+    end
+  end
+end

data/app/controllers/openstax/api/v1/oauth_based_api_controller.rb

@@ -0,0 +1,17 @@
+module OpenStax
+  module Api
+    module V1
+
+      class OauthBasedApiController < ApiController
+
+        respond_to :json
+
+        def current_user
+          @current_api_user ||= ApiUser.new(doorkeeper_token, lambda { super })
+        end
+           
+      end
+
+    end
+  end
+end

data/app/models/openstax/api/api_user.rb

@@ -0,0 +1,82 @@
+# A "user" (lowercase 'u') of an API can take one of several forms.
+# 
+#   1. It can just be a User (capital 'U') based on session data (e.g. 
+#      someone who logs into this site and then uses this site's Backbone 
+#      interface).
+#   2. It can be a combination of a Doorkeeper Application and a User, 
+#      given via OAuth's Authorization or Implicit flows.
+#   3. It can just be a Doorkeeper Application, given through OAuth's
+#      Client Credentials flow.  
+# 
+# This API class gives us a way to abstract out these cases and also
+# gives us accessors to get the Application and User objects, if available.
+
+module OpenStax
+  module Api
+    class ApiUser
+
+      def initialize(doorkeeper_token, non_doorkeeper_user_proc)
+        # If we have a doorkeeper_token, derive the Application and User
+        # from it.  If not, we're in case #1 above and the User should be 
+        # retrieved from the alternative proc provided in arguments and 
+        # there is no application.
+        #
+        # In both cases, don't actually retrieve any data -- just save off
+        # procs that can get it for us.  This could save us some queries.
+
+        if doorkeeper_token
+          @application_proc = lambda { doorkeeper_token.application }
+          @user_proc = lambda {
+            doorkeeper_token.resource_owner_id ? 
+              User.find(doorkeeper_token.resource_owner_id) :
+              nil
+          }
+        else
+          @user_proc = non_doorkeeper_user_proc
+          @application_proc = lambda { nil }
+        end
+      end
+
+      # Returns a Doorkeeper::Application or nil 
+      # TODO should we have a NoApplication like NoUser (or maybe should
+      # NoUser just be replaced with nil)
+      def application
+        @application ||= @application_proc.call
+      end
+
+      # Can return an instance of User, AnonymousUser, or nil
+      def human_user
+        @user ||= @user_proc.call
+      end
+
+      ##########################
+      # Access Control Helpers #
+      ##########################
+
+      def can_do?(action, resource)
+        OSU::AccessPolicy.action_allowed?(action, self, resource)
+      end
+
+      def can_read?(resource)
+        can_do?(:read, resource)
+      end
+      
+      def can_create?(resource)
+        can_do?(:create, resource)
+      end
+      
+      def can_update?(resource)
+        can_do?(:update, resource)
+      end
+        
+      def can_destroy?(resource)
+        can_do?(:destroy, resource)
+      end
+
+      def can_sort?(resource)
+        can_do?(:sort, resource)
+      end
+
+    end
+  end
+end

data/app/representers/openstax/api/v1/representable_schema_printer.rb

@@ -0,0 +1,85 @@
+module OpenStax
+  module Api
+    module V1
+      class RepresentableSchemaPrinter
+
+        def self.json(representer, options={})
+          options[:include] ||= [:readable, :writeable]
+          options[:indent] ||= '  '
+
+          definitions = {}
+
+          schema = json_schema(representer, definitions, options)
+          schema[:definitions] = definitions
+
+          json_string = JSON.pretty_generate(schema, {indent: options[:indent]})
+
+          "\nSchema  {##{SecureRandom.hex(4)} .schema}\n------\n" +
+          "<pre class='code'>\n#{json_string}\n</pre>\n"
+        end
+
+      protected
+
+        def self.json_schema(representer, definitions, options={})
+          schema = {
+            # id: schema_id(representer),
+            # title: schema_title(representer),
+            type: "object",
+            properties: {},
+            required: []
+            # :$schema => "http://json-schema.org/draft-04/schema#"
+          }
+
+          representer.representable_attrs.each do |attr|
+            schema_info = attr.options[:schema_info] || {}
+
+            schema[:required].push(attr.name) if schema_info[:required]
+
+            next unless [options[:include]].flatten.any?{|inc| attr.send(inc.to_s+"?") || schema_info[:required]}
+            
+            attr_info = {}
+
+            if attr.options[:collection]
+              attr_info[:type] = "array"
+            else
+              attr_info[:type] = attr.options[:type].to_s.downcase if attr.options[:type]
+            end
+
+            schema_info.each do |key, value|
+              next if [:required].include?(key)
+              value = value.to_s.downcase if key == :type
+              attr_info[key] = value
+            end
+
+            decorator = attr.options[:decorator].try(:is_a?, Proc) ? nil : attr.options[:decorator]
+
+            if decorator
+              relative_schema_id(decorator).tap do |id|
+                attr_info[:$ref] = "#/definitions/#{id}"
+                definitions[id] ||= json_schema(decorator, definitions, options)
+              end
+            end
+
+            schema[:properties][attr.name.to_sym] = attr_info
+          end
+
+          schema
+        end
+
+        def self.schema_title(representer)
+          representer.name.gsub(/Representer/,'')
+        end
+
+        def self.schema_id(representer)
+          "http://#{OpenStax::Api::Engine::MAIN_APP_NAME.to_s}.openstax.org/" +
+          "#{schema_title(representer).downcase.gsub(/::/,'/')}"
+        end
+
+        def self.relative_schema_id(representer)
+          representer.name.gsub(/Representer/,'').downcase.gsub(/::/,'/')
+        end
+
+      end
+    end
+  end
+end

data/lib/openstax_api/constraints.rb

@@ -0,0 +1,21 @@
+module OpenStax
+  module Api
+    class Constraints
+      cattr_accessor :main_app_name
+      
+      def initialize(options)
+        @version = options[:version]
+        @default = options[:default]
+      end
+
+      def api_accept_header
+        self.main_app_name ||= OpenStax::Api::Engine::MAIN_APP_NAME.underscore
+        "application/vnd.#{self.main_app_name}.openstax.#{@version.to_s}"
+      end
+      
+      def matches?(req)
+        @default || req.headers['Accept'].try(:include?, api_accept_header)
+      end
+    end
+  end
+end

data/lib/openstax_api/doorkeeper_extensions.rb

@@ -0,0 +1,22 @@
+module OpenStax
+  module Api
+    module DoorkeeperExtensions
+      # Add some fields to Doorkeeper::Application
+      def is_human?
+        false
+      end
+      
+      def is_application?
+        true
+      end
+      
+      def is_admin?
+        false
+      end
+    end
+  end
+end
+
+OpenStax::Api::Engine.config.after_initialize do
+  Doorkeeper::Application.send :include, OpenStax::Api::DoorkeeperExtensions
+end

data/lib/openstax_api/engine.rb

@@ -0,0 +1,20 @@
+module OpenStax
+  module Api
+    class Engine < ::Rails::Engine
+      isolate_namespace OpenStax::Api
+
+      config.after_initialize do
+        MAIN_APP_NAME = ::Rails.application.class.parent_name
+      end
+
+      config.generators do |g|
+        g.test_framework      :rspec,        :fixture => false
+        g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      end
+
+      ActiveSupport::Inflector.inflections do |inflect|
+        inflect.acronym 'OpenStax'
+      end
+    end
+  end
+end

data/lib/openstax_api/route_extensions.rb

@@ -0,0 +1,17 @@
+require 'openstax_api/constraints'
+
+module OpenStax
+  module Api
+    module RouteExtensions
+      def api(version = :v1, default = false)
+        constraints = Constraints.new(version: version, default: default)
+        namespace :api, defaults: {format: 'json'} do
+          scope(module: version,
+                constraints: constraints) { yield }
+        end
+      end
+    end
+  end
+end
+
+ActionDispatch::Routing::Mapper.send :include, OpenStax::Api::RouteExtensions

data/lib/openstax_api/version.rb

@@ -0,0 +1,5 @@
+module OpenStax
+  module Api
+    VERSION = "0.0.1"
+  end
+end

data/lib/openstax_api.rb

@@ -0,0 +1,8 @@
+require 'openstax_api/engine'
+require 'openstax_api/doorkeeper_extensions'
+require 'openstax_api/route_extensions'
+
+module OpenStax
+  module Api
+  end
+end

data/spec/app/controllers/openstax/api/v1/api_controller_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+module OpenStax
+  module Api
+    module V1
+      describe ApiController do
+        # Nothing to test yet
+      end
+    end
+  end
+end

data/spec/app/controllers/openstax/api/v1/oauth_based_api_controller_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+module OpenStax
+  module Api
+    module V1
+      describe OauthBasedApiController do
+        # Nothing to test yet
+      end
+    end
+  end
+end

data/spec/app/models/openstax/api/api_user_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+module OpenStax
+  module Api
+    describe ApiUser do
+      let(:user) { User.create }
+      let(:application) { double('Doorkeeper::Application') }
+      let(:doorkeeper_token) { double('Doorkeeper::AccessToken') }
+      let(:non_doorkeeper_user_proc) { lambda { user } }
+
+      context 'human user' do
+        let(:api_user) { ApiUser.new(nil, non_doorkeeper_user_proc) }
+        
+        it 'has a human_user but no application' do
+          expect(api_user.application).to be_nil
+          expect(api_user.human_user).to eq(user)
+        end
+      end
+
+      context 'application with human user' do
+        let(:api_user) { ApiUser.new(doorkeeper_token,
+                                     non_doorkeeper_user_proc) }
+
+        it 'has a human_user and an application' do
+          doorkeeper_token.stub(:application).and_return(application)
+          doorkeeper_token.stub(:resource_owner_id).and_return(user.id)
+
+          expect(api_user.application).to eq(application)
+          expect(api_user.human_user).to eq(user)
+        end
+      end
+
+      context 'application only' do
+        let(:api_user) { ApiUser.new(doorkeeper_token,
+                                     non_doorkeeper_user_proc) }
+
+        it 'has an application but no human_user' do
+          doorkeeper_token.stub(:application).and_return(application)
+          doorkeeper_token.stub(:resource_owner_id).and_return(nil)
+
+          expect(api_user.application).to eq(application)
+          expect(api_user.human_user).to be_nil
+        end
+      end
+    end
+  end
+end

data/spec/app/representers/openstax/api/v1/representable_schema_printer_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module OpenStax
+  module Api
+    module V1
+      describe RepresentableSchemaPrinter do
+        it 'must print model schemas' do
+          schema = RepresentableSchemaPrinter.json(UserRepresenter)
+          expect(schema).to include('Schema')
+          expect(schema).to include('.schema')
+          expect(schema).to include('------')
+          expect(schema).to include("<pre class='code'>")
+          expect(schema).to include("{\n  \"type\": \"object\",\n  \"properties\": {\n    \"username\": {\n    },\n    \"password_hash\": {\n    }\n  },\n  \"required\": [\n\n  ],\n  \"definitions\": {\n  }\n}")
+          expect(schema).to include('</pre>')
+        end
+      end
+    end
+  end
+end

data/spec/dummy/README.md

@@ -0,0 +1 @@
+Dummy application used to test the openstax_api gem.

data/spec/dummy/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/spec/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,15 @@
+// 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
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/spec/dummy/app/assets/stylesheets/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/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/spec/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/spec/dummy/app/models/user.rb

@@ -0,0 +1,2 @@
+class User < ActiveRecord::Base
+end

data/spec/dummy/app/representers/user_representer.rb

@@ -0,0 +1,8 @@
+require 'representable/json'
+
+module UserRepresenter
+  include Roar::Representer::JSON
+  
+  property :username
+  property :password_hash
+end