apify 0.3.3 → 0.4.0

data/README.md

@@ -1,14 +1,286 @@
-apify
+Apify
 =====
 
-Installation
-------------
+Apify lets you bolt a [JSON](http://en.wikipedia.org/wiki/JSON) API onto your Rails application.
+Optional features are auto-generated API documentation, request validation with [JSON Schema](http://json-schema.org/)
+and a client class to consume Apify APIs from Ruby code.
+
+
+Two minute quickstart
+---------------------
 
 Install the gem with
 
     sudo gem install apify
 
-...
+For Rails 2, add the following to your `environment.rb`:
+
+    config.gem 'apify'
+
+For Rails 3, add the following to your `Gemfile`:
+
+    gem 'apify'
+
+Describe your API actions in `models/api.rb`:
+
+    class Api < Apify::Api
+      get :ping do
+        respond do
+          { 'message' => 'pong' }
+        end
+      end
+    end
+
+Create a controller to serve your API in `controllers/api_controller.rb`:
+
+    class ApiController < Apify::ApiController
+      api Api
+    end
+
+Connect the routes to your API in `config/routes.rb`:
+
+    ActionController::Routing::Routes.draw do |map|
+      Api.draw_routes(map)
+    end
+
+You have now exposed an API action under `http://host/api/ping`.
+
+
+Protocol
+--------
+
+If you are planning to consume your Apify API with the `Apify::Client` class, you won't need to know most of this. Nonetheless, this is what you're getting into:
+
+- Apify is about sending JSON objects (hashes) back and forth. No fancy envelope formats.
+- An Apify API defines actions with a name and HTTP method (`GET, POST, PUT, DELETE`).
+- API actions are accessed over HTTP. Each action gets its own route.
+- API actions can take arguments. Those are serialized into a **single** HTTP parameter `args` as JSON. This is to simplify client code that consumes your API (nested params are hard).
+- Successful responses are returned with a status of 200 (OK).
+- The body of a successful response is always a hash, serialized as JSON.
+- Requests that have errors are returned with a status of 500 (internal server error). The body of a error response is an error message in the response's content type (won't be JSON in most cases).
+
+
+Defining API actions
+--------------------
+
+API actions are defined in a model such as `models/api.rb`:
+
+- This model needs to inherit from `Apify::Api`.
+- An API method has a name and a  HTTP method (`GET, POST, PUT, DELETE`)
+- An API action always returns a hash. If an API action returns nil, Apify will turn that into an empty hash for you.
+
+Here is an example for a simple, reading API action:
+
+    get :ping do
+      respond do
+        { 'message' => 'pong' }
+      end
+    end
+
+Action arguments can be accessed through the `args` hash. Its keys are always strings, never symbols.
+
+Here is an example for an API action that takes an argument:
+
+    post :hello do
+      respond do
+        { 'message' => 'Hello ' + args['name'] }
+      end
+    end
+
+
+Schemas
+-------
+
+You can describe the expected format of method arguments and response values using [JSON Schema](http://json-schema.org/). This lets you define rules like that an argument is required or must be in a given format.
+
+Schemas are an optional feature, but providing schemas has some benefits:
+
+- Your actions don't need to handle unexpected arguments (remember that strangers are going to call your code).
+- You don't need to worry about responding with values that break your own contract. Apify will validate your own responses and raise an error if they don't validate.
+- Apify can auto-generate public documentation for actions with schemas. This documentation will contain generated examples for a successful request and response and also offer your schemas for download.
+
+You can provide a schema for arguments, a schema for response values, or both. Here is the `hello` action from the above example with schemas:
+
+    post :hello do
+
+      schema :args do
+        object('name' => string)
+      end
+
+      schema :value do
+        object('message' => string)
+      end
+
+      respond do
+        { 'message' => 'Hello ' + args['name'] }
+      end
+
+    end
+
+Your API now allows to download the schema and an auto-generated example in JSON format:
+
+- POST http://host/api/hello?schema=args
+- POST http://host/api/hello?example=args
+- POST http://host/api/hello?schema=value
+- POST http://host/api/hello?example=value
+
+Here is another example for a more complex schema:
+
+    get :contacts do
+      schema :value do
+        array(
+          object(
+            'name' => string,
+            'phone' => integer,
+            'phone_type' => enum(string, 'home', 'office'),
+            'email' => optional(email),
+            'favorite' => boolean
+          )
+        )
+      end
+    end
+
+
+Auto-generated API documentation
+--------------------------------
+
+Every Apify API comes with auto-generated HTML documentation:
+
+- The documentation can be accessed from the `docs` action of an `ApiController`, e.g. http://host/api/docs
+- The documentation contains parts of this README (protocol, instructions to use the Ruby client)
+- If your actions have schemas, the documentation includes those schemas and request/response examples generated from them.
+
+You can give your actions descriptions to make the API documentation even more useful:
+
+    post :hello do
+
+      description 'Says hello to the given name.'
+
+      respond do
+        { 'message' => 'Hello ' + args['name'] }
+      end
+
+    end
+
+
+
+Authentication
+--------------
+
+If your API uses a single username and password for all requests, you can activate basic authentication like this:
+
+    class ApiController < ApplicationController::Base
+      api Api
+      authenticate :user => 'api', :password => 'secret'
+    end
+
+If your use case is more complex, just roll your own authentication. Your `ApiController` is just a regular controller.
+
+
+Consuming an API with the Ruby client
+-------------------------------------
+
+An easy way to consume an Apify API is to use the <code>Apify::Client</code> class:
+
+- The client calls an Apify API with a Ruby hash as argument and returns the response as a Ruby hash.
+- It takes care of the protocol details and lets your users focus on exchanging data.
+- Your users will only need the `apify` gem. There are no dependencies on Rails.
+- The auto-generated documentation contains these instructions on how to install and use the client class.
+
+You already know how to require the `apify` gem from a Rails application. This is how you require the client class when your code is not a Rails application:
+
+    require 'rubygems'
+    gem 'apify'
+    require 'apify/client'
+
+Here is an example for how to use the client class:
+
+    client = Apify::Client.new(:host => 'localhost:3000', :user => 'api', :password => 'secret')
+    client.post('/api/hello', :name => 'Jack') # { 'message' => 'Hello Jack' }
+
+Errors can be caught and inspected like this:
+
+    begin
+      client.get('/api/hello', :name => 'Jack') # { 'message' => 'Hello Jack' }
+    rescue Apify::RequestFailed => e
+      puts "Oh no! The API request failed."
+      puts "Message: #{e.message}"
+      puts "Response: #{e.response_body}"
+    end
+
+
+Dealing with dates and timestamps
+---------------------------------
+
+Unfortunately dates and timestamps are not among the data types defined by JSON and JSON Schema. You can work around this in any way you like, but Apify supports a default approach:
+
+- The workaround supported by Apify is to handle a date as a string formatted like "2011-05-01" and a timestamp as a string formatted like "2011-05-01 12:00:04".
+- Aside from being easy to parse, you can feed such strings into a model's date or time field and ActiveRecord will convert them into `Date` and `Time` objects.
+- Apify gives you helper methods `sql_date` and `sql_datetime` to support this pattern in your schemas and actions.
+
+Here are examples for actions that deal with dates and timestamps this way:
+
+    get :now do
+      schema :value do
+        object('now' => sql_datetime)
+      end
+      respond do
+        { 'now' => sql_datetime(Time.now) }
+      end
+    end
+
+    get :today do
+      schema :value do
+        object('today' => sql_date)
+      end
+      respond do
+        { 'today' => sql_date(Date.today) }
+      end
+    end
+
+
+Testing API actions
+-------------------
+
+Since your API actions end up being vanilla Ruby methods that turn argument hashes into value hashes, you can test them without special tools.
+
+Here is an example in RSpec:
+
+    describe Api, 'hello' do
+
+      it 'should greet the given name' do
+        Api.post(:hello, :name => 'Jack').should == { 'message' => 'Hello Jack' }
+      end
+
+      it 'should require a name argument' do
+        expect { Api.post(:hello) }.to raise_error(Apify::Invalid)
+      end
+
+    end
+
+
+Custom routing
+--------------
+
+You can create a route for each action of an API by adding this to your `config/routes.rb`:
+
+    ActionController::Routing::Routes.draw do |map|
+      Api.draw_routes(map)
+    end
+
+This will create URLs like `/api/ping`, `/api/hello`, etc. You can change the `/api` prefix like this:
+
+    ActionController::Routing::Routes.draw do |map|
+      Api.draw_routes(map, :base_path => 'interface/v1')
+    end
+
+You can also forego the automatic route generation completely and roll your own URLs:
+
+    ActionController::Routing::Routes.draw do |map|
+      map.connect 'api/ping', :controller => 'api', :action => 'ping', :conditions { :method => :get }
+      map.connect 'api/hello', :controller => 'api', :action => 'hello', :conditions { :method => :post }
+    end
+
 
 Rails 3 compatibility
 ---------------------

data/VERSION

@@ -1 +1 @@
-0.3.3
+0.4.0

data/apify.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{apify}
-  s.version = "0.3.3"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Henning Koch"]
-  s.date = %q{2010-08-28}
+  s.date = %q{2010-08-29}
   s.description = %q{Compact definition of JSON APIs for Rails applications. }
   s.email = %q{github@makandra.de}
   s.extra_rdoc_files = [
@@ -97,6 +97,7 @@ Gem::Specification.new do |s|
      "spec/app_root/lib/console_with_fixtures.rb",
      "spec/app_root/script/console",
      "spec/controllers/api_controller_spec.rb",
+     "spec/models/api_spec.rb",
      "spec/rcov.opts",
      "spec/spec.opts",
      "spec/spec_helper.rb"
@@ -123,6 +124,7 @@ Gem::Specification.new do |s|
      "spec/app_root/config/environment.rb",
      "spec/app_root/config/routes.rb",
      "spec/controllers/api_controller_spec.rb",
+     "spec/models/api_spec.rb",
      "examples/client/client.rb",
      "examples/host/app/controllers/application_controller.rb",
      "examples/host/app/controllers/api_controller.rb",

data/app/views/apify/api/_client.html.erb

@@ -11,13 +11,19 @@ First install the Apify gem:
 
 <pre><code>sudo gem install apify</code></pre>
 
+If your client code is not a Rails application:
+
+<pre><code>require 'rubygems'
+gem 'apify'
+require 'apify/client'</code></pre>
+
 In Rails 2, add the following to your environment.rb:
 
-<pre><code>config.gem 'aegis'</code></pre>
+<pre><code>config.gem 'apify'</code></pre>
 
 In Rails 3, add the following to your Gemfile:
 
-<pre><code>gem 'aegis'</code></pre>
+<pre><code>gem 'apify'</code></pre>
 
 <h3>Usage</h3>
 

data/app/views/apify/api/_overview.html.erb

@@ -3,7 +3,6 @@
 <ul>
   <li>The API works by exchanging messages encoded in <a href="http://en.wikipedia.org/wiki/JSON">JSON</a>.</li>
   <li>There are no fancy message formats, it's all just sending arbitrary JSON objects back and forth.</li>
-  <li>There are some optional features like validating requests with schemas, but you don't need to use them if you don't like.</li>
-  <li>Building a lient that consumes the API is very straightforward. Also if you use Ruby, there is a helpful <a href="#api_client">client class</a> available.</li>
+  <li>Building a lient cthat consumes the API is very straightforward. Also if you use Ruby, there is a helpful <a href="#api_client">client class</a> available.</li>
 </ul>
 

data/app/views/apify/api/_protocol.html.erb

@@ -3,7 +3,7 @@
 <h3>Requests</h3>
 
 <ul>
-  <li>The API is accessed over plain HTTP.</li>
+  <li>The API is accessed over HTTP.</li>
   <% if authentication_configured? %>
     <li>HTTP basic authentication is used.</li>
   <% end %>

data/lib/apify/action.rb

@@ -23,9 +23,7 @@ module Apify
       if block
         @responder = block
       else
-        Apify::Exchange.new.tap do |exchange|
-          exchange.respond(args, self)
-        end
+        Apify::Exchange.new.respond(args, self)
       end
     end
 

data/lib/apify/api.rb

@@ -2,7 +2,7 @@ module Apify
   class Api
     class << self
 
-      def action(method, name, &block)
+      def action(method, name, args = {}, &block)
         method = method.to_sym
         name = name.to_sym
         if block
@@ -10,24 +10,25 @@ module Apify
           indexed_actions[name][method] = action
           actions << action
         else
-          indexed_actions[name][method] or raise "Unknown API action: #{name}"
+          action = indexed_actions[name][method] or raise "Unknown API action: #{name}"
+          action.respond(args)
         end
       end
 
-      def get(name, &block)
-        action(:get, name, &block)
+      def get(*args, &block)
+        action(:get, *args, &block)
       end
 
-      def post(name, &block)
-        action(:post, name, &block)
+      def post(*args, &block)
+        action(:post, *args, &block)
       end
 
-      def put(name, &block)
-        action(:put, name, &block)
+      def put(*args, &block)
+        action(:put, *args, &block)
       end
 
-      def delete(name, &block)
-        action(:delete, name, &block)
+      def delete(*args, &block)
+        action(:delete, *args, &block)
       end
 
       def actions

data/lib/apify/api_controller.rb

@@ -59,17 +59,17 @@ module Apify
     
     def respond_with_action(action)
       args = params[:args].present? ? JSON.parse(params[:args]) : {}
-      exchange = action.respond(args)
-      render_api_response(exchange, "#{action.name}.json")
+      render_successful_request(action.respond(args), "#{action.name}.json")
+    rescue Exception => e
+      render_failed_request(e.message)
     end
 
-    def render_api_response(exchange, filename)
-      # p exchange.value
-      if exchange.successful?
-        send_data exchange.value.to_json, :status => '200', :type => 'application/json', :filename => filename
-      else
-        send_data exchange.value, :status => '500', :type => 'text/plain', :filename => filename
-      end
+    def render_successful_request(value, filename)
+      send_data value.to_json, :status => '200', :type => 'application/json', :filename => filename
+    end
+
+    def render_failed_request(message)
+      send_data message, :status => '500', :type => 'text/plain'
     end
 
     def render_method_not_allowed(method)

data/lib/apify/client.rb

@@ -36,10 +36,12 @@ module Apify
     def request(method, path, args = nil)
       url = build_url(path)
       args ||= {}
-      json = RestClient.send(method, url, :args => args.to_json)
+      params = { :args => args.to_json }
+      [:get, :head].include?(method) and params = { :params => params }
+      json = RestClient.send(method, url, params)
       JSON.parse(json)
     rescue RestClient::Unauthorized => e
-      raise Apify::RequestFailed.new("Unauthorized")
+      raise Apify::Unauthorized.new("Unauthorized")
     rescue RestClient::ExceptionWithResponse => e
       raise Apify::RequestFailed.new("API request failed with status #{e.http_code}", e.http_body)
     end

data/lib/apify/errors.rb

@@ -1,4 +1,5 @@
 module Apify
+
   class RequestFailed < StandardError
 
     attr_reader :response_body
@@ -9,4 +10,11 @@ module Apify
     end
 
   end
+
+  class Unauthorized < Apify::RequestFailed
+  end
+
+  class Invalid < Apify::RequestFailed
+  end
+
 end

data/lib/apify/exchange.rb

@@ -6,22 +6,17 @@ module Apify
 
     def initialize
       @value = nil
-      @error = false
       @args = nil
     end
 
-    def successful?
-      not @error
-    end
-
     def respond(args, action)
-      logging_errors do
-        @args = args
-        validate(@args, action.schema(:args), 'Invalid request args')
-        @value = instance_eval(&action.responder) || {}
-        validate(@value, action.schema(:value), 'Invalid response value')
-      end
-      successful?
+      # hash_class = defined?(HashWithIndifferentAccess) ? HashWithIndifferentAccess : ActiveSupport::HashWithIndifferentAccess
+      @args = args.stringify_keys
+      validate(@args, action.schema(:args), 'Invalid request args')
+      @value = instance_eval(&action.responder) || {}
+      @value.stringify_keys!
+      validate(@value, action.schema(:value), 'Invalid response value')
+      @value
     end
 
     private
@@ -31,16 +26,10 @@ module Apify
     def validate(object, schema, message_prefix)
       JSON::Schema.validate(object, schema) if schema
     rescue JSON::Schema::ValueError => e
-      raise "#{message_prefix}: #{e.message}"
+      @value = nil
+      raise Apify::Invalid.new("#{message_prefix}: #{e.message}")
     end
 
-    def logging_errors(&block)
-      block.call
-    rescue Exception => e
-      @error = true
-      @value = e.message
-    end
-    
     def sql_datetime(time)
       time.present? ? time.strftime("%Y-%m-%d %H:%M:%S") : nil
     end

data/spec/apify/client_spec.rb

@@ -4,20 +4,36 @@ describe Apify::Client do
 
   it "raise an exception if authorization is missing" do
     client = Apify::Client.new(:host => 'host')
-    stub_http_request(:get, 'http://host/api').to_return(:status => 401, :body => 'the body')
-    expect { client.get '/api' }.to raise_error(Apify::RequestFailed)
+    stub_request(:post, 'http://host/api/method').to_return(:status => 401, :body => 'the body')
+    expect { client.post '/api/method' }.to raise_error(Apify::RequestFailed)
   end
 
   it "raise an exception if there is a server error" do
     client = Apify::Client.new(:host => 'host')
-    stub_http_request(:get, 'http://host/api').to_return(:status => 500, :body => 'the body')
-    expect { client.get '/api' }.to raise_error(Apify::RequestFailed)
+    stub_request(:post, 'http://host/api/method').to_return(:status => 500, :body => 'the body')
+    expect { client.post '/api/method' }.to raise_error(Apify::RequestFailed)
   end
 
   it "should return the parsed JSON object if the request went through" do
     client = Apify::Client.new(:host => 'host')
-    stub_http_request(:get, 'http://host/api').to_return(:status => 200, :body => '{ "key": "value" }')
-    client.get('/api').should == { 'key' => 'value' }
+    stub_request(:post, 'http://host/api/method').to_return(:status => 200, :body => '{ "key": "value" }')
+    client.post('/api/method').should == { 'key' => 'value' }
+  end
+
+  it "should call API methods with arguments" do
+    client = Apify::Client.new(:host => 'host')
+    stub_request(:post, 'http://host/api/hello').to_return(:status => 200, :body => '{}')
+    args = { :name => 'Jack' }
+    client.post('/api/hello', args)
+    WebMock.should have_requested(:post, "http://host/api/hello").with(:body => { :args => args.to_json })
+  end
+
+  it "should call GET actions correctly" do
+    client = Apify::Client.new(:host => 'host')
+    args = { :name => 'Jack' }
+    stub_request(:get, 'http://host/api/hello').with(:query => { :args => args.to_json }).to_return(:status => 200, :body => '{}')
+    client.get('/api/hello', args)
+    WebMock.should have_requested(:get, "http://host/api/hello").with(:query => { :args => args.to_json })
   end
 
 end

data/spec/app_root/app/models/api.rb

@@ -12,6 +12,18 @@ class Api < Apify::Api
     end
   end
 
+  post :hello do
+    schema :args do
+      object('name' => string)
+    end
+    schema :value do
+      object('message' => string)
+    end
+    respond do
+      { 'message' => "Hello #{args['name']}" }
+    end
+  end
+
   post :echo_args do
     respond do
       args
@@ -20,19 +32,13 @@ class Api < Apify::Api
 
   post :with_args_schema do
     schema :args do
-      { "type" => "object",
-        "properties" => {
-          "string_arg" => string
-      }}
+      object("string_arg" => string)
     end
   end
 
   post :with_value_schema do
     schema :value do
-      { "type" => "object",
-        "properties" => {
-          "string_value" => string
-      }}
+      object("string_value" => string)
     end
     respond do
       args

data/spec/models/api_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+describe 'Convenient testing of Api models' do
+
+  it 'should allow to test response objects directly' do
+    Api.post(:hello, :name => 'Jack').should == { 'message' => 'Hello Jack' }
+  end
+
+  it 'should raise an exception on errors' do
+    expect { Api.post(:hello) }.to raise_error(Apify::Invalid)
+    expect { Api.post(:fail) }.to raise_error(StandardError)
+  end
+
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 3
-  - 3
-  version: 0.3.3
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Henning Koch
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-28 00:00:00 +02:00
+date: 2010-08-29 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -143,6 +143,7 @@ files:
 - spec/app_root/lib/console_with_fixtures.rb
 - spec/app_root/script/console
 - spec/controllers/api_controller_spec.rb
+- spec/models/api_spec.rb
 - spec/rcov.opts
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -193,6 +194,7 @@ test_files:
 - spec/app_root/config/environment.rb
 - spec/app_root/config/routes.rb
 - spec/controllers/api_controller_spec.rb
+- spec/models/api_spec.rb
 - examples/client/client.rb
 - examples/host/app/controllers/application_controller.rb
 - examples/host/app/controllers/api_controller.rb