haveapi 0.3.2 → 0.4.0

data/doc/protocol.md

@@ -2,7 +2,7 @@
 HaveAPI defines the format for the self-description and URLs where the self-description
 can be found.
 
-## Self-description
+# Self-description
 The API is self-describing. It documents itself. Clients use the self-description
 to work with the API. The Self-description contains access URLs, HTTP methods,
 input and output parameters and their validators.
@@ -20,7 +20,19 @@ Thanks to this ability, API changes immediately reflects in all clients without
 changing a single line of code. A client can also be used on all APIs with compatible
 self-describing format, without any changes at all.
 
-## Envelope
+# Protocol versioning
+Protocol version defines the form and contents of
+
+ - the envelope,
+ - API description,
+ - data transfers.
+
+Protocol version is in the form `<major>.<minor>`. `major` is incremented
+whenever a change is made to the protocol that breaks backward compatibility.
+When backward compatibility is kept and only some new features are added to the
+protocol, `major` stays and `minor` is incremented.
+
+# Envelope
 In addition to output format specified below, every API response
 is wrapped in an envelope.
 The envelope reports if action succeeded or failed, provides return value or error
@@ -36,12 +48,23 @@ messages.
           }
       }
 
-## Description format
+Responses for `OPTIONS` requests also send a protocol version in the envelope:
+
+    "version": <version>
+
+# Description format
 In this document, the self-description is encoded in JSON. However, it can
 be encoded in any of the supported output formats.
 
-### Version
-Version is described as:
+## API version
+
+<a href="/doc/protocol.png">
+<img src="/doc/protocol.png"
+     alt="Diagram representing the structure of an API version"
+	 width="600">
+</a>
+
+API version is described as:
 
     {
         "authentication": {
@@ -50,15 +73,15 @@ Version is described as:
         "resources": {
             ... resources ...
         },
-	"meta": {
-	    "namespace": "_meta"
-	},
+        "meta": {
+            "namespace": "_meta"
+        },
         "help": "/<version>/"
     }
 
 See appropriate section for detailed description of each section.
 
-### Authentication
+## Authentication
 HaveAPI defines an interface for implementing custom authentication methods.
 HTTP basic and token authentication is built-in.
 
@@ -66,12 +89,12 @@ Authentication methods can be set per API version. They are a part of
 the self-description, but must be understood by the client.
 The client can choose whichever available authentication method he prefers.
 
-#### HTTP basic authentication
+### HTTP basic authentication
 HTTP basic authentication needs no other configuration, only informs about its presence.
 
     "basic": {}
 
-#### Token authentication
+### Token authentication
 Token authentication contains a resource ``token``, that is used
 to acquire and revoke token.
 
@@ -114,7 +137,7 @@ Token can be revoked by calling the ``revoke`` action.
 
 The format for ``resources`` section is the same as for any other resource.
 
-### Resources
+## Resources
 Each resource is described as:
 
     "<resource_name>": {
@@ -127,7 +150,7 @@ Each resource is described as:
         }
     }
 
-### Actions
+## Actions
 Every action is described as:
 
     "<action_name>": {
@@ -157,7 +180,7 @@ Every action is described as:
         "help": "URL to get this very description of the action"
     }
 
-#### Layouts
+### Layouts
 Layout type is specified for input/output parameters. Thanks to the layout type,
 clients know how to send the request and how to interpret the response.
 
@@ -172,7 +195,7 @@ In client libraries, the ``object`` layout output usually results in returning
 an object that represents the instance of the resource. The parameters are defined
 as object properties and the like.
 
-#### Namespace
+### Namespace
 All input/output parameters are put in a namespace, which is usually
 the name of the resource.
 
@@ -184,10 +207,10 @@ For example:
         }
     }
 
-### Parameters
+## Parameters
 There are two parameter types.
 
-#### Data types
+### Data types
 The type can be one of:
 
  - String
@@ -202,16 +225,133 @@ The type can be one of:
             "label": "Label for this parameter",
             "description": "Describe it's meaning",
             "type": "<one of the data types>",
-            "choices": a list or a hash of accepted values
             "validators": ... validators ...,
             "default": "default value that is used if the parameter is omitted"
         }
 
-If the choices are in a list, than it is a list of accepted values.
-If the choices are in a hash, the keys of that hash are accepted values,
+
+#### Validators
+Every parameter has its own validators. Any of the following validators
+may be present. Input value must pass through all validators in order
+to be considered valid.
+
+##### Acceptance
+Used when a parameter must have one specific value.
+
+    "accept": {
+        "value": <value to accept>,
+        "message": "has to be <value>"
+    }
+
+##### Presence
+The parameter must be present. If `empty` is `false`, leading and trailing
+whitespace is stripped before the check.
+
+    "present": {
+        empty: true/false,
+        message: "must be present"
+    }
+
+##### Confirmation
+Used to confirm that two parameters have either the same value or not have the
+same value. The former can be used e.g. to verify that passwords are same
+and the latter to give two different e-mail addresses.
+
+    "confirm": {
+        "equal": true/false,
+        "parameter": <parameter_name>,
+        "message": "must (or must not) be the same as <parameter_name>"
+    }
+
+##### Inclusion
+The parameter can contain only one of given options.
+
+    "include": {
+        "values": ["list", "of", "allowed", "values"],
+        "message": "%{value} cannot be used"
+    }
+
+If the `values` are a list, than it is a list of accepted values.
+If the `values` are a hash, the keys of that hash are accepted values,
 values in that hash are to be shown in UI.
 
-#### Resource association
+    "include": {
+        "values": {
+            "one": "Fancy one",
+            "two": "Fancy two"
+        },
+        "message": "%{value} cannot be used"
+    }
+
+##### Exclusion
+The parameter can be set to anything except values listed here.
+
+    "exclude": {
+        "values": ["list", "of", "excluded", "values"],
+        "message": "%{value} cannot be used"
+    }
+
+##### Specific format
+If `match` is true, the parameter must pass given regular expression.
+Otherwise it must not pass the regular expression.
+
+    "format": {
+        "rx": "regular expression",
+        "match": true/false,
+	"description": "human-readable description of the regular expression",
+        "message": "%{value} is not in a valid format"
+    }
+
+##### Length
+Useful only for `String` and `Text` parameters. Checks the length of given string.
+It may check either
+
+ - minimum
+ - maximum
+ - minimum and maximum
+ - constant length
+
+The length validator must therefore contain one or more checks, but cannot
+contain both min/max and equality.
+
+Length range:
+
+    "length": {
+        "min": 0,
+        "max": 99,
+        "message": "length has to be in range <0,99>"
+    }
+
+Constant length:
+
+    "length": {
+        "equals": 10,
+        "message": "length has to be 10"
+    }
+
+##### Numericality
+Numericality implies that the parameter must be a number, i.e. `Integer`, `Float`
+or `String` containing only digits. It can check that the number is in a specified
+range and can provide a step. The validator can contain one or more of these conditions.
+
+    "number": {
+        "min": 0,
+        "max": 99,
+        "step": 3,
+        "mod": 3,
+        "even": true/false,
+        "odd": true/false
+    }
+
+##### Custom validation
+Custom validation cannot be documented by the API. The developer may or may not
+provide information that some non-documented validation takes place. The documentation
+contains only the description of the validations that may be shown to the user,
+but is not evaluated client-side, only server-side.
+
+    "custom": "description of custom validation"
+
+### Resource association
 This is used for associations between resources, e.g. car has a wheel.
 
     "<parameter_name>": {
@@ -243,7 +383,7 @@ can show the human-friendly label instead of just an ID.
         "<value of value_label from description>": "<label>"
     }
 
-### Examples
+## Examples
 Examples are described in a generic way, so that every client can
 render them according to its syntax.
 
@@ -258,24 +398,24 @@ render them according to its syntax.
         "comment": "Description of the example"
     }
 
-### Metadata
+## Metadata
 Metadata can be global and per-object. Global metadata are sent once for each
 response, where as per-object are sent with each object that is a part of the
 response.
 
     {
         "global": {
-	    "input": ... parameters or null ...,
-	    "output: ... parameters or null ...
-	} or null,
+            "input": ... parameters or null ...,
+            "output: ... parameters or null ...
+        } or null,
         
-	"object": {
-	    "input": ... parameters or null ...,
-	    "output: ... parameters or null ...
-	} or null,
+        "object": {
+            "input": ... parameters or null ...,
+            "output: ... parameters or null ...
+        } or null,
     }
 
-### List API versions
+## List API versions
 Send request ``OPTIONS /?describe=versions``. The description format:
 
     {
@@ -283,11 +423,11 @@ Send request ``OPTIONS /?describe=versions``. The description format:
         "default": <which version is default>
     }
 
-### Describe default version
+## Describe default version
 Send request ``OPTIONS /?describe=default`` the get the description
 of the default version.
 
-### Describe the whole API
+## Describe the whole API
 It is possible to get self-description of all versions at once.
 
 Send request ``OPTIONS /``. The description format:
@@ -301,20 +441,20 @@ Send request ``OPTIONS /``. The description format:
         }
     }
 
-## Authorization
+# Authorization
 Actions may require different levels of authorization. HaveAPI provides means for
 implementing authorization, but it is not self-described.
 
 If the user is authenticated when requesting self-description, only allowed
 resources/actions/parameters will be returned.
 
-## Input/output formats
+# Input/output formats
 For now, the only supported input format is JSON.
 
 Output format can be chosen by a client. However, no other format than JSON is built-in.
 The output format can be chosen with HTTP header ``Accept``.
 
-## Request
+# Request
 Action URL and HTTP method the client learns from the self-description.
 
 Example request:
@@ -332,7 +472,7 @@ Example request:
         }
     }
 
-## Response
+# Response
 Clients know how to interpret the response thanks to the layout type they learn
 from the self-description.
 
@@ -349,7 +489,7 @@ Example response to the request above:
                 "name": "Very Name",
                 "role": "admin"
             }
-	},
+        },
         "message": null,
         "errors: null
     }

data/doc/protocol.plantuml

@@ -0,0 +1,220 @@
+@startuml
+
+class Version {
+	help : String
+}
+
+class Meta {
+	namespace : String
+}
+
+abstract class Authentication {
+	
+}
+
+class Basic {
+	
+}
+
+class Token {
+	http_header : String
+	query_parameter : String
+}
+
+class Resource {
+	name : String
+	description : String
+}
+
+class Action {
+	name : String
+	auth : Bool
+	description : String
+	aliases : list
+	url : String
+	method : String
+	help : String
+}
+
+class Example {
+	title : String
+	request : hash
+	response : hash
+	comment : String
+}
+
+class Parameters {
+	layout : String
+	namespace : String
+}
+
+abstract class Parameter {
+	required : Bool
+	label : String
+	description : String
+	type : String
+}
+
+class InputParameter {
+	default : any
+}
+
+class OutputParameter {
+	
+}
+
+abstract class ResourceParameter {
+	value_id : String
+	value_label : String
+}
+
+class TypedInputParameter {
+	
+}
+
+class ResourceInputParameter {
+}
+
+class TypedOutputParameter {
+	
+}
+
+class ResourceOutputParameter {
+}
+
+class ResourceLink {
+	url : String
+	method : String
+	help : String
+}
+
+
+class ActionMeta {
+}
+
+abstract class Validator {
+	message : String
+}
+
+class AcceptanceValidator {
+	value : any
+}
+
+class ConfirmationValidator {
+	equal : Bool
+}
+
+class CustomValidator {
+	description : String
+}
+
+class ExclusionValidator {
+	values : list
+}
+
+class FormatValidator {
+	rx : RegExp
+	match : Bool
+	description : String
+}
+
+abstract class InclusionValidator {
+	
+}
+
+class ArrayInclusionValidator {
+	values : list
+}
+
+class HashInclusionValidator {
+	values : hash
+}
+
+abstract class LengthValidator {
+	
+}
+
+class EqualLengthValidator {
+	equals : Integer
+}
+
+class RangeLengthValidator {
+	min : Integer
+	max : Integer
+}
+
+class NumericalityValidator {
+	min : Number
+	max : Number
+	step : Number
+	mod : Integer
+	odd : Bool
+	even : Bool
+}
+
+class PresenceValidator {
+	empty : Bool
+}
+
+Version -- Meta
+Version *-- Authentication
+
+Authentication <|-- Basic
+Authentication <|-- Token
+
+Token *-- Resource
+
+Version *-- Resource
+
+Resource *-- Resource
+Resource *-- Action
+
+Action *-- Example
+Action -- Parameters : input
+Action -- Parameters : output
+Action -- ActionMeta : object
+Action -- ActionMeta : global
+
+ActionMeta -- Parameters : input
+ActionMeta -- Parameters : output
+
+Parameters *-- Parameter
+
+Parameter <|-- InputParameter
+Parameter <|-- OutputParameter
+Parameter <|-- ResourceParameter
+
+ResourceParameter <|-- ResourceInputParameter
+ResourceParameter <|-- ResourceOutputParameter
+ResourceParameter -- Resource : associated with
+
+InputParameter <|-- TypedInputParameter
+InputParameter <|-- ResourceInputParameter
+
+TypedInputParameter *-- Validator
+
+Validator <|-- AcceptanceValidator
+Validator <|-- ConfirmationValidator
+ConfirmationValidator -- InputParameter : confirms
+Validator <|-- CustomValidator
+Validator <|-- ExclusionValidator
+Validator <|-- FormatValidator
+Validator <|-- InclusionValidator
+InclusionValidator <|-- ArrayInclusionValidator
+InclusionValidator <|-- HashInclusionValidator
+Validator <|-- LengthValidator
+LengthValidator <|-- EqualLengthValidator
+LengthValidator <|-- RangeLengthValidator
+Validator <|-- NumericalityValidator
+Validator <|-- PresenceValidator
+
+OutputParameter <|-- TypedOutputParameter
+OutputParameter <|-- ResourceOutputParameter
+
+ResourceInputParameter -- ResourceLink : value
+ResourceInputParameter -- ResourceLink : choices
+
+ResourceOutputParameter -- ResourceLink : value
+ResourceOutputParameter -- ResourceLink : choices
+
+@enduml

data/haveapi.gemspec

@@ -5,7 +5,7 @@ require 'haveapi/version'
 Gem::Specification.new do |s|
   s.name        = 'haveapi'
   s.version     = HaveAPI::VERSION
-  s.date        = '2015-08-13'
+  s.date        = '2016-01-20'
   s.summary     =
   s.description = 'Framework for creating self-describing APIs'
   s.authors     = 'Jakub Skokan'
@@ -15,16 +15,12 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '~> 2.0'
 
-  s.add_runtime_dependency 'activerecord', '~> 4.1.6'
   s.add_runtime_dependency 'require_all'
   s.add_runtime_dependency 'json'
-  s.add_runtime_dependency 'sinatra'
-  s.add_runtime_dependency 'mysql'
-  s.add_runtime_dependency 'sinatra-activerecord'
+  s.add_runtime_dependency 'sinatra', '~> 1.4.6'
+  s.add_runtime_dependency 'tilt', '~> 1.4.1'
+  s.add_runtime_dependency 'redcarpet', '~> 3.3.4'
   s.add_runtime_dependency 'rake'
-  s.add_runtime_dependency 'github-markdown', '~> 0.6.6'
-
-  s.add_development_dependency 'rspec'
-  s.add_development_dependency 'railties'
-  s.add_development_dependency 'rack-test'
+  s.add_runtime_dependency 'github-markdown', '~> 0.6.9'
+  s.add_runtime_dependency 'nesty', '~> 1.0.2'
 end

data/lib/haveapi/action.rb

@@ -11,7 +11,16 @@ module HaveAPI
 
     include Hookable
 
-    has_hook :exec_exception
+    has_hook :exec_exception,
+        desc: 'Called when unhandled exceptions occurs during Action.exec',
+        args: {
+            action: 'HaveAPI::Action instance',
+            exception: 'exception instance',
+        },
+        ret: {
+            status: 'true or false, indicating whether error should be reported',
+            message: 'error message sent to the user',
+        }
 
     attr_reader :message, :errors, :version
     attr_accessor :flags
@@ -65,10 +74,14 @@ module HaveAPI
       def initialize
         return if @initialized
 
-        input.exec
-        model_adapter(input.layout).load_validators(model, input) if model
+        check_build("#{self}.input") do
+          input.exec
+          model_adapter(input.layout).load_validators(model, input) if model
+        end
 
-        output.exec
+        check_build("#{self}.output") do
+          output.exec
+        end
 
         model_adapter(input.layout).used_by(:input, self)
         model_adapter(output.layout).used_by(:output, self)
@@ -76,14 +89,30 @@ module HaveAPI
         if @meta
           @meta.each_value do |m|
             next unless m
-            m.input && m.input.exec
-            m.output && m.output.exec
+
+            check_build("#{self}.meta.input") do
+              m.input && m.input.exec
+            end
+
+            check_build("#{self}.meta.output") do
+              m.output && m.output.exec
+            end
           end
         end
 
         @initialized = true
       end
 
+      def validate_build
+        check_build("#{self}.input") do
+          input.validate_build
+        end
+
+        check_build("#{self}.output") do
+          output.validate_build
+        end
+      end
+
       def model_adapter(layout)
         ModelAdapter.for(layout, resource.model)
       end