haveapi 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 503ec7b15af7ae22f652f749407b54fa61c0fe91
-  data.tar.gz: 9a1fe935c87601e227b3a1038bef6bd71c4d6280
+  metadata.gz: 97a0780e86ee6d9273d743c2c6b7c87ba053b19d
+  data.tar.gz: aa2f1bda2b113b1ea0452da5940dabc1617bf68e
 SHA512:
-  metadata.gz: 7234a6fb2a44fd3ab8ed68efe5363565944ca191c4617b40474da3658f922681ae7a16b7706c1ab58b31f9c806ea2fe571531b4a3c5b03e567c3413e86bd7abd
-  data.tar.gz: f994d620f9847d66e35fdc25dcb0f3857a4e4f1dfc2acf7e6b9d74b416d013af0b09fe2217957fecbf956a862e5a722c68550e42238093e8b5a49a8fb9fef9ef
+  metadata.gz: f665c8857e439f36280aae5634f3ff98cce618d645f6b4104a6d00c7a82727bd787edffed0ca7ed2f3daf60646711105e2d408b58f2557b40e773916a665afac
+  data.tar.gz: 29bcfa9af9295e10bde9ead47df70bca5d185ea79ea656660f80a26b4ed54cf3f35ea6e142b88f2f7ff6480f92080c4172d8e8986f912700bd6d57f0f1fcd34c

data/CHANGELOG

@@ -0,0 +1,12 @@
+* Wed Jan 20 2016 - version 0.4.0
+- Introduced protocol version, currently 1.0
+- Renamed certain API configuration methods
+- Document defined hooks in yardoc
+- Implicit API version
+- Include input parameter validators in the protocol
+- Present validator from ActiveRecord is not imported to controller
+- Clean-up dependencies
+- Cross-link resources in online API documentation
+- JSON schema of the documentation protocol
+- UML diagram representing the documentation protocol
+- Improved error reporting in action definition

data/Gemfile

@@ -1,12 +1,12 @@
 source 'https://rubygems.org'
+gemspec
 
-gem 'activerecord'
-gem 'require_all'
-gem 'json'
-gem 'sinatra'
-gem 'mysql'
-gem 'sinatra-activerecord'
-gem 'rake'
-gem 'rspec'
-gem 'rack-test'
-gem 'railties'
+group :test do
+  gem 'rspec'
+  gem 'rack-test'
+end
+
+group :activerecord do
+  gem 'activerecord', '~> 4.1.14'
+  gem 'sinatra-activerecord', '~> 2.0.9'
+end

data/README.md

@@ -2,7 +2,7 @@ HaveAPI
 =======
 A framework for creating self-describing APIs in Ruby.
 
-Note: HaveAPI is under heavy development. It is not stable, its interface may change.
+Note: HaveAPI is in heavy development. It is not stable, its interface may change.
 
 ## What is a self-describing API?
 A self-describing API responds to HTTP method `OPTIONS` and returns description
@@ -14,29 +14,33 @@ Clients use the self-description to learn how to communicate with the API,
 which they otherwise know nothing about.
 
 ## Main features
-- Creates RESTful APIs
+- Creates RESTful APIs usable even with simple HTTP client, should it be needed
 - Handles network communication, input/output formats and parameters
   on both server and client, you need only to define resources and actions
-- By writing the code you get the documentation which is available to all clients
+- By writing the code you get the documentation for free, it is available to all clients
 - Auto-generated online HTML documentation
 - Generic interface for clients - one client can be used to access all APIs
   using this framework
 - Ruby, PHP and JavaScript clients already available
 - A change in the API is immediately reflected in all clients
 - Supports API versioning
-- Ready for ActiveRecord - validators from models are included in the
-  self-description
+- ORM integration
+  - ActiveRecord
+    - integrated with controller
+    - loads and documents validators from models
+    - eager loading
+  - easy to support other ORM frameworks
 
 ## Usage
 This text might not be complete or up-to-date, as things still often change.
 Full use of HaveAPI may be seen
-in [vpsadminapi](https://github.com/vpsfreecz/vpsadminapi), which may serve
-as an example of how are things meant to be used.
+in [vpsadmin-api](https://github.com/vpsfreecz/vpsadmin-api)
+([online doc](https://api.vpsfree.cz)), which may serve as an example of how
+are things meant to be used.
 
 All resources and actions are represented by classes. They all must be stored
-in a module, whose name is later given to HaveAPI.
-
-HaveAPI then searches all classes in that module and constructs your API.
+in a module, whose name is later given to HaveAPI. HaveAPI then searches all
+classes in this module and builds your API.
 
 For the purposes of this document, all resources will be in module `MyAPI`.
 
@@ -136,7 +140,7 @@ module MyAPI
 
       # Helper method returning a query for all users
       def query
-	::User.all
+        ::User.all
       end
 
       # This method is called if the request has meta[:count] = true
@@ -215,7 +219,6 @@ class BasicAuth < HaveAPI::Authentication::Basic::Provider
 end
 
 api.use_version(:all)
-api.set_default_version(1)
 api.auth_chain << BasicAuth
 api.mount('/')
 
@@ -254,6 +257,10 @@ is not self-described.
 If the user is authenticated when requesting self-description, only allowed
 resources, actions and parameters will be returned.
 
+## Validation of input data
+Because validators are a part of the API's documentation, the clients can
+perform client-side validation before the data is sent to the API server.
+
 ## Available clients
 These clients completely rely on the API description and can be used for all
 APIs that are using HaveAPI.

data/Rakefile

@@ -1,7 +1,30 @@
 require 'bundler/gem_tasks'
 require 'rspec/core'
 require 'rspec/core/rake_task'
+require 'active_support/core_ext/string/inflections'
+require 'haveapi'
+require 'haveapi/tasks/yard'
 
 RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = FileList['spec/**/*_spec.rb']
 end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb']
+    t.options = [
+        '--protected',
+        '--output-dir=html_doc',
+        '--files=doc/*.md',
+        '--files=doc/*.html'
+    ]
+    t.before = Proc.new do
+      document_hooks.call
+      render_doc_file('doc/json-schema.erb', 'doc/JSON-Schema.html').call
+    end
+  end
+
+rescue LoadError
+end

data/doc/hooks.erb

@@ -0,0 +1,35 @@
+<%
+	def render_hash(hash)
+		return 'none' unless hash
+		'<dl>' + hash.map { |k,v| "<dt>#{k}</dt><dd>#{v}</dd>" }.join('') + '</dl>'
+	end
+%>
+# Hooks
+<% HaveAPI::Hooks.hooks.each do |klass, hooks| %>
+##<%= klass %>
+	<% hooks.each do |name, hook| %>
+### <%= name %>
+<table>
+	<tr>
+		<td style="vertical-align: top;">Description:</td>
+		<td><%= hook[:desc] %></td>
+	</tr>
+	<tr>
+		<td style="vertical-align: top;">Context:</td>
+		<td><%= hook[:context] || 'current' %></td>
+	</tr>
+	<tr>
+		<td style="vertical-align: top;">Arguments:</td>
+		<td><%= render_hash(hook[:args]) %></td>
+	</tr>
+	<tr>
+		<td style="vertical-align: top;">Initial value:</td>
+		<td><%= render_hash(hook[:initial]) %></td>
+	</tr>
+	<tr>
+		<td style="vertical-align: top;">Return value:</td>
+		<td><%= render_hash(hook[:ret]) %></td>
+	</tr>
+</table>
+	<% end %>
+<% end %>

data/doc/index.md

@@ -3,4 +3,5 @@ HaveAPI documentation
 
  - [README](doc/readme)
  - [Protocol definition](doc/protocol.md)
+ - [JSON schema of the documentation protocol](doc/json-schema)
  - [How to create a client](doc/create-client.md)

data/doc/json-schema.erb

@@ -0,0 +1,369 @@
+<%
+require 'json'
+
+DEFINITIONS = {
+    version: {
+        type: :object,
+        properties: {
+            authentication: {
+                type: :object,
+                properties: {
+                    basic: { '$ref' => '#/definitions/auth_basic' },
+                    token: { '$ref' => '#/definitions/auth_token' },
+                }
+            },
+            resources: {
+                type: :object,
+                '$ref' => '#/definitions/resources'
+            },
+            meta: {
+                type: :object,
+                properties: {
+                    namespace: {
+                        type: :string,
+                        default: '_meta'
+                    }
+                }
+            },
+            help: { type: :string }
+        }
+    },
+
+    auth_basic: {
+        type: :object,
+    },
+
+    auth_token: {
+        type: :object,
+        properties: {
+            http_header: {
+                type: :string,
+                default: 'X-HaveAPI-Auth-Token'
+            },
+            query_parameter: {
+                type: :string,
+                default: '_auth_token'
+            },
+            resources: {
+                type: :object,
+                '$ref' => '#/definitions/resources'
+            }
+        }
+    },
+
+    resources: {
+        type: :object,
+        patternProperties: {
+            '^[a-z_]+$' => {
+                type: :object,
+                properties: {
+                    description: { type: :string },
+                    actions: {
+                        '$ref' => '#/definitions/actions'
+                    },
+                    resources: {
+                        '$ref' => '#/definitions/resources'
+                    }
+                }
+            }
+        }
+    },
+
+    actions: {
+        type: :object,
+        patternProperties: {
+            '^[a-z_]+$' => {
+                type: :object,
+                properties: {
+                    auth: { type: :boolean },
+                    description: { type: :string },
+                    aliases: {
+                        type: :array,
+                        items: { type: :string }
+                    },
+                    input: { '$ref' => '#/definitions/input_parameters' },
+                    output: { '$ref' => '#/definitions/output_parameters' },
+					meta: { '$ref' => '#/definitions/action_meta' },
+                    examples: {
+                        type: :object,
+                        properties: {
+                            title: { type: :string },
+                            request: { type: :object },
+                            response: { type: :object },
+                            comment: { type: :string },
+                        }
+                    },
+                    url: { type: :string },
+                    method: { type: :string },
+                    help: { type: :string }
+                }
+            }
+        }
+        
+    },
+
+    input_parameters: {
+        type: :object,
+        properties: {
+            parameters: {
+                type: :object,
+                patternProperties: {
+                    '^[a-z_]+$' => {
+                        type: :object,
+                        oneOf: [
+                            {
+                                title: 'Data type',
+                                type: :object,
+                                properties: {
+                                    required: { type: :boolean },
+                                    label: { type: :string },
+                                    description: { type: :string },
+                                    type: {
+                                        type: :string,
+                                        enum: %w(String Text Integer Float Datetime Boolean)
+                                    },
+                                    validators: { '$ref' => '#/definitions/input_validators' },
+                                    default: {}
+                                }
+                            },
+                            {
+                                title: 'Resource',
+                                type: :object,
+                                properties: {
+                                    required: { type: :boolean },
+                                    label: { type: :string },
+                                    description: { type: :string },
+                                    type: {
+                                        type: :string,
+                                        enum: %w(Resource)
+                                    },
+                                    resource: { type: :array },
+                                    value_id: { type: :string },
+                                    value_label: { type: :string },
+                                    value: {
+                                        type: :object,
+                                        properties: {
+                                            url: { type: :string },
+                                            method: { type: :string },
+                                            help: { type: :string },
+                                        }
+                                    },
+                                    choices: {
+                                        type: :object,
+                                        properties: {
+                                            url: { type: :string },
+                                            method: { type: :string },
+                                            help: { type: :string },
+                                        }
+                                    }
+                                }
+                            }
+                        ]
+                    }
+                }
+            },
+            layout: {},
+            namespace: {}
+        }
+    },
+
+    input_validators: {
+        type: :object,
+        properties: {
+            accept: {
+                type: :object,
+                properties: {
+                    value: {},
+                    message: { type: :string }
+                }
+            },
+            confirm: {
+                type: :object,
+                properties: {
+                    equal: { type: :boolean },
+                    parameter: { type: :string },
+                    message: { type: :string }
+                }
+            },
+            custom: { type: :string },
+            exclude: {
+                type: :object,
+                properties: {
+                    values: { type: :array },
+                    message: { type: :string }
+                }
+            },
+            format: {
+                type: :object,
+                properties: {
+                    rx: { type: :string },
+                    match: { type: :boolean },
+                    description: { type: :string },
+                    message: { type: :string }
+                }
+            },
+            include: {
+                type: :object,
+                properties: {
+                    values: {
+                        oneOf: [
+                            {
+                                title: 'Array of allowed values',
+                                type: :array
+                            },
+                            {
+                                title: 'Hash of allowed values',
+                                type: :object
+                            }
+
+                        ]
+                    },
+                    message: { type: :string }
+                }
+            },
+            length: {
+                oneOf: [
+                    {
+                        title: 'Equality',
+                        type: :object,
+                        properties: {
+                            equals: { type: :integer },
+                            message: { type: :string },
+                        }
+                    },
+                    {
+                        title: 'Interval',
+                        type: :object,
+                        properties: {
+                            min: { type: :integer },
+                            max: { type: :integer },
+                            message: { type: :string },
+                        }
+                    }
+                ]
+            },
+            number: {
+                type: :object,
+                properties: {
+                    min: { type: :number },
+                    max: { type: :number },
+                    step: { type: :number },
+                    mod: { type: :integer },
+                    odd: { type: :boolean },
+                    even: { type: :boolean },
+                    message: { type: :string },
+                }
+            },
+            present: {
+                type: :object,
+                properties: {
+                    empty: { type: :boolean },
+                    message: { type: :string },
+                }
+            }
+        }
+    },
+
+    output_parameters: {
+        type: :object,
+        properties: {
+          parameters: {},
+          layout: {},
+          namespace: {}
+        }
+    },
+
+    action_meta: {
+        type: :object,
+        properties: {
+            object: {
+                input: { '$ref' => '#/definitions/input_parameters' },
+                output: { '$ref' => '#/definitions/output_parameters' },
+            },
+            global: {
+                input: { '$ref' => '#/definitions/input_parameters' },
+                output: { '$ref' => '#/definitions/output_parameters' },
+            }
+        }
+    }
+}
+
+ROOTS = {
+    all: {
+        title: 'Describe all API versions',
+        type: :object,
+        properties: {
+            default_version: {},
+            versions: {
+                type: :object,
+                patternProperties: {
+                    '^.+$' => { '$ref' => '#/definitions/version' }
+                },
+                properties: {
+                    default: { '$ref' => '#/definitions/version' }
+                },
+            }
+        },
+        required: %i(default_version versions)
+    },
+
+    versions: {
+        title: 'Show available API versions',
+        type: :object,
+        properties: {
+            versions: { type: :array },
+            default: {}
+        },
+        required: %i(versions default)
+    },
+
+    default: {
+        title: 'Describe only the default version of the API',
+		'$ref' => '#/definitions/version'
+	},
+
+	envelope: {
+        title: 'All response are wrapped in this envelope',
+		type: :object,
+        properties: {
+			version: {},
+			status: { type: :boolean },
+            response: { type: :object },
+            message: { type: :string },
+			errors: {
+                type: :object,
+				patternProperties: {
+                    '^.+$' => { type: :array }
+                },
+            },
+        },
+        required: ['status'],
+	}
+}
+
+urls = {
+    '/' => {
+        root: :all,
+        definitions: true
+    },
+    '/?describe=versions' => {
+        root: :versions
+    },
+    '/?describe=default' => {
+        root: :default,
+        definitions: true
+    },
+}
+%>
+
+<h1 id="envelope">Envelope</h1>
+<pre><code><%= JSON.pretty_generate(ROOTS[:envelope]) %></code></pre>
+
+<%
+urls.each do |url, opts|
+  hash = ROOTS[opts[:root]]
+  hash = hash.merge(DEFINITIONS) if opts[:definitions]
+%>
+<h1 id="<%= opts[:root] %>">OPTIONS <%= url %></h1>
+<pre><code><%= JSON.pretty_generate(hash) %></code></pre>
+<% end %>