apify 0.3.0

data/.gitignore

@@ -0,0 +1,7 @@
+doc
+pkg
+*.gem
+.idea
+spec/app_root/log/*
+
+

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Henning Koch
+
+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,25 @@
+apify
+=====
+
+Installation
+------------
+
+Install the gem with
+
+    sudo gem install apify
+
+...
+
+Rails 3 compatibility
+---------------------
+
+We cannot guarantee Rails 3 compatibility at this point, but we will upgrade the gem when Rails 3 is released.
+
+Credits
+-------
+
+Henning Koch
+
+{makandra.com}[http://makandra.com/]
+
+{gem-session.com}[http://gem-session.com/]

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+desc 'Default: Run all specs.'
+task :default => :spec
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new() do |t|
+  t.spec_opts = ['--options', "\"spec/spec.opts\""]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc 'Generate documentation for the apify gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'apify'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "apify"
+    gemspec.summary = "Compact definition of JSON APIs for Rails applications. "
+    gemspec.email = "github@makandra.de"
+    gemspec.homepage = "http://github.com/makandra/apify"
+    gemspec.description = "Compact definition of JSON APIs for Rails applications. "
+    gemspec.authors = ["Henning Koch"]
+    gemspec.add_dependency 'json'
+    gemspec.add_dependency 'jsonschema'
+    gemspec.add_dependency 'rest-client'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/apify.gemspec

@@ -0,0 +1,103 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{apify}
+  s.version = "0.3.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.description = %q{Compact definition of JSON APIs for Rails applications. }
+  s.email = %q{github@makandra.de}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "apify.gemspec",
+     "app/helpers/apify_helper.rb",
+     "app/views/apify/api/_actions.html.erb",
+     "app/views/apify/api/_client.html.erb",
+     "app/views/apify/api/_overview.html.erb",
+     "app/views/apify/api/_protocol.html.erb",
+     "app/views/apify/api/docs.html.erb",
+     "lib/apify.rb",
+     "lib/apify/action.rb",
+     "lib/apify/api.rb",
+     "lib/apify/api_controller.rb",
+     "lib/apify/client.rb",
+     "lib/apify/errors.rb",
+     "lib/apify/exchange.rb",
+     "lib/apify/schema_helper.rb",
+     "spec/apify/action_spec.rb",
+     "spec/apify/client_spec.rb",
+     "spec/app_root/app/controllers/api_controller.rb",
+     "spec/app_root/app/controllers/application_controller.rb",
+     "spec/app_root/app/models/api.rb",
+     "spec/app_root/config/boot.rb",
+     "spec/app_root/config/database.yml",
+     "spec/app_root/config/environment.rb",
+     "spec/app_root/config/environments/in_memory.rb",
+     "spec/app_root/config/environments/mysql.rb",
+     "spec/app_root/config/environments/postgresql.rb",
+     "spec/app_root/config/environments/sqlite.rb",
+     "spec/app_root/config/environments/sqlite3.rb",
+     "spec/app_root/config/routes.rb",
+     "spec/app_root/lib/console_with_fixtures.rb",
+     "spec/app_root/script/console",
+     "spec/controllers/api_controller_spec.rb",
+     "spec/rcov.opts",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/makandra/apify}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Compact definition of JSON APIs for Rails applications.}
+  s.test_files = [
+    "spec/apify/action_spec.rb",
+     "spec/apify/client_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/app_root/app/controllers/api_controller.rb",
+     "spec/app_root/app/controllers/application_controller.rb",
+     "spec/app_root/app/models/api.rb",
+     "spec/app_root/lib/console_with_fixtures.rb",
+     "spec/app_root/config/environments/in_memory.rb",
+     "spec/app_root/config/environments/mysql.rb",
+     "spec/app_root/config/environments/postgresql.rb",
+     "spec/app_root/config/environments/sqlite.rb",
+     "spec/app_root/config/environments/sqlite3.rb",
+     "spec/app_root/config/boot.rb",
+     "spec/app_root/config/environment.rb",
+     "spec/app_root/config/routes.rb",
+     "spec/controllers/api_controller_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_runtime_dependency(%q<jsonschema>, [">= 0"])
+      s.add_runtime_dependency(%q<rest-client>, [">= 0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<jsonschema>, [">= 0"])
+      s.add_dependency(%q<rest-client>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<jsonschema>, [">= 0"])
+    s.add_dependency(%q<rest-client>, [">= 0"])
+  end
+end
+

data/app/helpers/apify_helper.rb

@@ -0,0 +1,14 @@
+module ApifyHelper
+
+  def api_docs_artifact(action, artifact, nature)
+    show_id = "#{nature}_#{artifact}_for_#{action.name}"
+    show_link = link_to_function('show', "document.getElementById('#{show_id}').style.display = 'block';")
+    download_url = url_for(:action => action.name, artifact.to_sym => nature.to_s)
+    download_tooltip = "#{action.method.to_s.upcase} #{download_url} to download"
+    download_link = link_to('download', download_url, :method => action.method, :title => download_tooltip)
+    json = JSON.pretty_generate(action.send(artifact, nature))
+    embedded = "<pre id='#{show_id}' style='display: none'>#{json}</pre>"
+    "#{artifact.to_s.humanize} (#{show_link}, #{download_link})#{embedded}".html_safe
+  end
+
+end

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

@@ -0,0 +1,38 @@
+<h2 id="api_actions">Available actions</h2>
+
+<% api.actions.each do |action| %>
+
+  <div class="action">
+
+    <h3><%= action.method.to_s.upcase %> <%= action.name %></h3>
+
+    <% if action.description %>
+      <p><%=h action.description %></p>
+    <% end %>
+
+    <dl>
+      <dt>Arguments</dt>
+      <dd>
+        <% if action.takes_args? %>
+          <%= api_docs_artifact(action, :schema, :args) %>
+          <br />
+          <%= api_docs_artifact(action, :example, :args) %>
+        <% else %>
+          none
+        <% end %>
+      </dd>
+      <dt>Return value</dt>
+      <dd>
+        <% if action.returns_value? %>
+          <%= api_docs_artifact(action, :schema, :value) %>
+          <br />
+          <%= api_docs_artifact(action, :example, :value) %>
+        <% else %>
+          none
+        <% end %>
+      </dd>
+    </dl>
+
+  </div>
+
+<% end %>

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

@@ -0,0 +1,38 @@
+<h2 id="api_client">Using the Ruby client</h2>
+
+<p>
+  An easy way to use the API is to use the <code>Apify::Client</code> class.
+  It takes care of the protocol details and lets you focus on exchanging data.
+</p>
+
+<h3>Installation</h3>
+
+First install the Apify gem:
+
+<pre><code>sudo gem install apify</code></pre>
+
+In Rails 2, add the following to your environment.rb:
+
+<pre><code>config.gem 'aegis'</code></pre>
+
+In Rails 3, add the following to your Gemfile:
+
+<pre><code>gem 'aegis'</code></pre>
+
+<h3>Usage</h3>
+
+<pre><code>client = Apify::Client.new(:host => 'localhost:3000', :user => 'api', :password => 'secret')
+client.post('/api/hello', :name => 'Jack') # { 'message' => 'Hello Jack' }</code></pre>
+
+<p>
+  Errors can be caught and inspected like this:
+</p>
+
+<pre><code>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
+</code></pre>

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

@@ -0,0 +1,9 @@
+<h2>Overview</h2>
+
+<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>
+</ul>
+

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

@@ -0,0 +1,38 @@
+<h2 id="api_protocol">Protocol</h2>
+
+<h3>Requests</h3>
+
+<ul>
+  <li>The API is accessed over plain HTTP.</li>
+  <% if authentication_configured? %>
+    <li>HTTP basic authentication is used.</li>
+  <% end %>
+  <li>Take care to use the correct HTTP method (<code>GET, POST, PUT, DELETE</code>) as documented for each action.</li>
+  <li>Some (but not all) actions take arguments.</li>
+  <li>Action arguments are serialized into a <strong>single</strong> HTTP parameter <code>args</code> as JSON.</li>
+  <li>You can download an example for a request's arguments by appending <code>?example=args</code> to the action URL.</li>
+  <li>You can download a <a href="http://json-schema.org/">JSON schema</a> for a valid request by appending <code>?schema=args</code> to the action URL. Using the schema and a library like <a href="http://github.com/Constellation/ruby-jsonchema">jasonschema</a> you can validate your requests before sending them. The API will only process requests that conform to this schema.</li>
+</ul>
+
+<h3>Responses</h3>
+
+<ul>
+  <li>Successful requests are returned with a status of 200 (OK).</li>
+  <li>The body of a successful response is always a hash, serialized as JSON.</li>
+  <li>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 plain text (no JSON here).</li>
+  <li>You can download an example for a successful response value by appending <code>?example=value</code> to the action URL.</li>
+  <li>You can download a <a href="http://json-schema.org/">JSON schema</a> for a successful response by appending <code>?schema=value</code> to the URL. The API guarantees that all responses conform to this schema.</li>
+</ul>
+
+<h3>Example for a request/response exchange</h3>
+
+<ol>
+  <li>
+    API client sends to API host: <code>POST http://api-host/api/hello?args=JSON</code>
+    <br />
+    where JSON is a serialized JSON object: <code>'{ "name": "Jack" }'</code>
+  </li>
+  <li>
+   API host returns a response with a status of 200 (OK) and a serialized JSON object as its body: <code>'{ "message": "Hello Jack" }'</code>
+  </li>
+</ol>

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

@@ -0,0 +1,66 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+  <head>
+    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type" />
+    <title>API documentation</title>
+    <style type="text/css">
+    <!--
+      body {
+        font-family: arial, helvetica, sans-serif;
+        font-size: 15px;
+        line-height: 19px;
+      }
+      #container {
+        max-width: 80%;
+        margin: 40px auto;
+      }
+      dt, dd {
+        margin-left: 0;
+        padding-left: 0;
+      }
+      dt {
+        font-weight: bold;
+      }
+      dl {
+        margin-bottom: 0;
+      }
+      h1, h2, h3, p, dd, ol, ul {
+        margin-bottom: 0.6em;
+        margin-top: 0;
+      }
+      h2 {
+        margin-top: 1em;
+      }
+      code {
+        font-family: courier new, monospace;
+        font-size: 15px;
+        background-color: #eee;
+        padding: 0 2px
+      }
+      pre {
+        background-color: #eee;
+        padding: 5px;
+      }
+      .action {
+        border: 1px dotted #777;
+        padding: 10px;
+        margin-bottom: 0.8em;
+        background-color: #f4f4f4;
+      }
+      .action dl dd:last-child {
+        margin-bottom: 0;
+      }
+
+    -->
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <h1>API documentation</h1>
+      <%= render :partial => 'apify/api/overview' %>
+      <%= render :partial => 'apify/api/protocol' %>
+      <%= render :partial => 'apify/api/client' %>
+      <%= render :partial => 'apify/api/actions' %>
+    </div>
+  </body>
+</html>

data/lib/apify.rb

@@ -0,0 +1,7 @@
+require 'apify/errors'
+require 'apify/action'
+require 'apify/exchange'
+require 'apify/api'
+require 'apify/schema_helper'
+require 'apify/api_controller'
+require 'apify/client'

data/lib/apify/action.rb

@@ -0,0 +1,98 @@
+module Apify
+  class Action
+
+    attr_reader :name, :description, :method
+
+    def initialize(method, name, &block)
+      @method = method
+      @name = name
+      @schemas = Hash.new({}.freeze)
+      instance_eval(&block)
+    end
+
+    def schema(nature, &block)
+      nature = nature.to_sym
+      if block
+        @schemas[nature] = eval_schema(block)
+      else
+        @schemas[nature]
+      end
+    end
+
+    def respond(args = nil, &block)
+      if block
+        @responder = block
+      else
+        Apify::Exchange.new.tap do |exchange|
+          exchange.respond(args, self)
+        end
+      end
+    end
+
+    def description(description = nil, &block)
+      if description || block
+        @description = description ? description : block.call
+      else
+        @description
+      end
+    end
+
+    def takes_args?
+      schema(:args) != {}
+    end
+
+    def returns_value?
+      schema(:value) != {}
+    end
+
+    def responder
+      @responder || lambda {}
+    end
+
+    def example(schema_nature)
+      example_for_schema(schema(schema_nature))
+    end
+
+    def uid
+      "#{method}_#{name}"
+    end
+
+    private
+
+    def example_for_schema(schema)
+      case schema['type']
+        when 'object'
+          {}.tap do |object|
+            if properties = schema['properties']
+              properties.each do |key, value|
+                object[key] = example_for_schema(value)
+              end
+            end
+          end
+        when 'array'
+          [].tap do |array|
+            if items = schema['items']
+              array.concat [example_for_schema(items)] * 2
+            end
+          end
+        when 'boolean'
+          true
+        when 'number'
+          2.5
+        when 'integer'
+          123
+        when 'string'
+          'string'
+        else
+         raise "Unknown schema type: #{schema['type']}"
+      end
+    end
+
+    def eval_schema(schema)
+      lathe = Object.new
+      lathe.extend Apify::SchemaHelper
+      lathe.instance_eval(&schema)
+    end
+
+  end
+end