haveapi 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ebf5f1d0fbc768717e2524ba3f39aacd309cfc99
-  data.tar.gz: fc682dfc13a3233775e4b277f5a28b898c4c39f6
+  metadata.gz: 6bd050d4c2bbaf7541cf8f8a353e41c20e4dc6da
+  data.tar.gz: 93f458319509dc615b1c1036e3729d16f5d4cd92
 SHA512:
-  metadata.gz: 3c6a7e2cf446b7a073abfc3c730d8e66a98bf08c352b436794955908eb81b991935c9e2407e95ce5c2d44d7076089580e5d2ff0aa796dacb19c017da74aca7b4
-  data.tar.gz: 122cf69cfd635ce62ec712d2d1d1d578cb8d5ddde30baa78b29fe7fc644bcfc1f865e9416b7157612487b3c0d8405f5c0544c3812da77d6fa6d3f02c12207461
+  metadata.gz: b5380970887ca813f6de8b6181c8d4dd941d0a84ff3a357b16176f18fb7073e7a8c29799c0af15a56d380f9b7f9a86ef8f66bc0d3b4bede815a7ba4a5f5b419d
+  data.tar.gz: a5481d5adb7e8cfae279243cfbc67be05fa56e2f984c6d908b73f207e50c1438bbe2befec0334930fe34ef4423b9473131387bac02084bc7a51f17829d3e9e10

data/.editorconfig

@@ -0,0 +1,15 @@
+# http://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+
+[*.{rb,erb}]
+indent_size = 2
+indent_style = space
+
+[*.plantuml]
+indent_size = 2
+indent_style = tab

data/CHANGELOG

@@ -1,3 +1,18 @@
+* Thu Nov 24 2016 - version 0.7.0
+- Blocking actions
+- Attempt to authenticate even for actions that don't require auth
+- Authentication methods have documented text descriptions
+- Examples can contain URL parameters, message, errors and HTTP status code
+- Examples are rendered in HaveAPI client languages, showing a snippet of
+  code generated from the example
+- Allow APIs to set HTTP status code
+- New hook HaveAPI::Server.description_exception
+- Online doc: link to prebuilt haveapi-webui at webui.haveapi.org
+- Print errors and exceptions in development mode
+- New extension ExceptionMailer
+- Fixed HaveAPI::Hooks.stop
+- Use DateTime.iso8601 to parse dates
+
 * Tue Oct 18 2016 - version 0.6.0
 - Token authentication: fix output of action renew
 - ActiveRecord: fix parsing of includes

data/README.md

@@ -1,29 +1,60 @@
 HaveAPI
 =======
-A framework for creating self-describing APIs in Ruby.
-
-Note: HaveAPI is in heavy development. It is not stable, its interface may change.
+HaveAPI defines a protocol for self-describing RESTful APIs. This repository contains
+documentation of said protocol and a reference implementation in Ruby, in the form of
+a framework for building APIs.
 
 ## What is a self-describing API?
 A self-describing API responds to HTTP method `OPTIONS` and returns description
 of available resources and their actions. The description contains
-full list of parameters, their labels, text notes, data types, validators
+a full list of parameters, their labels, text notes, data types, validators
 and example usage.
 
 Clients use the self-description to learn how to communicate with the API,
 which they otherwise know nothing about.
 
-## Main features
+## Motivation
+Whenever you create an API server, you need to implement clients in various programming
+languages to work with it. Even if you make all APIs similar using e.g. REST or SOAP,
+you still need clients to know what resources and actions the API has, what are their
+parameters, and so on.
+
+When your API speaks the HaveAPI protocol, you can use pre-created clients that will
+know how to work with it. You can do this by using this framework to handle all
+HaveAPI-protocol stuff for you, or you can implement the [protocol](doc/protocol.md)
+on your own.
+
+At the moment, the following clients are available:
+
+- Ruby client library and CLI: https://github.com/vpsfreecz/haveapi-client
+- PHP client: https://github.com/vpsfreecz/haveapi-client-php
+- JavaScript client: https://github.com/vpsfreecz/haveapi-client-js
+
+If there isn't a client in the language you need, you can [create it](doc/create-client.md).
+
+Complex applications can be built on top of these basic clients, e.g.:
+
+- [haveapi-webui](https://github.com/vpsfreecz/haveapi-webui), a generic web administration
+  for HaveAPI-based APIs
+- [haveapi-fs](https://github.com/vpsfreecz/haveapi-fs), a FUSE based filesystem that can
+  mount any HaveAPI-based API
+
+## Protocol features
 - 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 for free, it is available to all clients
-- Auto-generated online HTML documentation
+- A change in the API is immediately reflected in all clients when they re-download the
+  documentation
 - Generic interface for clients - one client can be used to access all APIs
-  using this framework
-- Ruby (with CLI), PHP and JavaScript (with web administration) clients already available
-- A change in the API is immediately reflected in all clients
+  that implement this protocol
 - Supports API versioning
+- Standardised authentication methods
+- Defines action input/output parameters and their validators
+- Clients can monitor progress of long-running actions
+
+## Server framework features
+- Handles network communication, authentication, authorization, input/output formats
+  and parameters, you need only to define resources and actions
+- By writing the code you get the documentation for free
+- Auto-generated online HTML documentation
 - ORM integration
   - ActiveRecord
     - integrated with controller
@@ -60,7 +91,7 @@ class User < ActiveRecord::Base
     in: %w(admin user),
     message '%{value} is not a valid role'
   }
-  
+
   # An example authentication with plain text password
   def self.authenticate(username, password)
     u = User.find_by(login: username)
@@ -79,42 +110,42 @@ module MyAPI
     # This resource belongs to version 1.
     # It is also possible to put resource to multiple versions, e.g. [1, 2]
     version 1
-    
+
     # Provide description for this resource
     desc 'Manage users'
-    
+
     # ActiveRecord model to load validators from
     model ::User
-    
+
     # Require authentication, this is the default
     auth true
-    
+
     # Create a named group of shared params, that may be later included
     # by actions.
     params(:id) do
       id :id, label: 'User ID'
     end
-    
+
     params(:common) do
       string :login, label: 'Login', desc: 'Used for authentication'
       string :full_name, label: 'Full name'
       string :role, label: 'User role', desc: 'admin or user'
     end
-    
+
     # Actions
     # Module HaveAPI::Actions::Default contains helper classes that define
     # HTTP methods and routes for generic actions.
     class Index < HaveAPI::Actions::Default::Index
       desc 'List all users'
-      
+
       # There are no input parameters
-      
+
       # Output parameters
       output(:object_list) do
         use :id
         use :common
       end
-      
+
       # Determine if current user can use this action.
       # allow/deny immediately returns from this block.
       # Default rule is deny.
@@ -122,7 +153,7 @@ module MyAPI
         allow if u.role == 'admin'
         deny  # deny is implicit, so it may be omitted
       end
-      
+
       # Provide example usage
       example do
         request({})
@@ -147,30 +178,30 @@ module MyAPI
       def count
         query.count
       end
-      
+
       # Execute action, return the list
       def exec
         query.limit(input[:limit]).offset(input[:offset])
       end
     end
-    
+
     class Create < HaveAPI::Actions::Default::Create
       desc 'Create new user'
-      
+
       input do
         use :common
       end
-      
+
       output do
         use :id
         use :common
       end
-      
+
       authorize do |u|
         allow if u.role == 'admin'
         deny
       end
-      
+
       example do
         request({
           user: {
@@ -185,10 +216,10 @@ module MyAPI
         })
         comment 'Create new user like this'
       end
-      
+
       def exec
         user = ::User.new(input)
-        
+
         if user.save
           ok(user)
         else
@@ -261,22 +292,10 @@ resources, actions and parameters will be returned.
 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.
-
-- Ruby client library and CLI: https://github.com/vpsfreecz/haveapi-client
-- PHP client: https://github.com/vpsfreecz/haveapi-client-php
-- JavaScript client: https://github.com/vpsfreecz/haveapi-client-js
-
-or [create your own client](doc/create-client.md).
-
-Complex applications can be built on top of these basic clients, e.g.:
-
-- [haveapi-webui](https://github.com/vpsfreecz/haveapi-webui), a generic web administration
-  for HaveAPI-based APIs
-- [haveapi-fs](https://github.com/vpsfreecz/haveapi-fs), a FUSE based filesystem that can
-  mount any HaveAPI-based API
+## Blocking actions
+Blocking mode is for actions whose execution is not immediate but takes an unspecified
+amount of time. HaveAPI protocol allows clients to monitor progress of such actions
+or cancel their execution.
 
 ## Read more
  - [Protocol definition](doc/protocol.md)

data/doc/create-client.md

@@ -23,25 +23,25 @@ A model paradigm (in no particular language):
 
     // Create client instance
     api = new HaveAPI.Client("https://your.api.tld")
-    
+
     // Authenticate
     api.authenticate("basic", {"user": "yourname", "password": "yourpassword"})
-    
+
     // Access resources and actions
     api.<resource>.<action>( { <parameters> } )
     api.user.new({"name": "Very Name", "password": "donottellanyone"})
     api.user.list()
     api.nested.resource.deep.list()
-    
+
     // Pass IDs to resources
     api.nested(1).resource(2).deep.list()
-    
+
     // Object-like access
     user = api.user.show(1)
     user.id
     user.name
     user.destroy()
-    
+
     // Logout
     api.logout()
 
@@ -96,3 +96,12 @@ Metadata channel is currently used to specify what associated resources should
 be prefetched and whether an object list should contain total number of items.
 
 Metadata is nothing more than a hash in input parameters under key `_meta`.
+
+## Blocking actions
+Useful for APIs with long-running actions. Clients can check state of such actions
+using resource `ActionState`. Because this resource is automatically present in all
+APIs that use blocking actions, client libraries expose this resource to the developer
+just as any other resource in the API.
+
+However, you may wish to integrate it in your client and provide ways for the action
+call to block/accept callbacks.

data/doc/json-schema.erb

@@ -81,15 +81,29 @@ DEFINITIONS = {
                         type: :array,
                         items: { type: :string }
                     },
+                    blocking: { type: :boolean },
                     input: { '$ref' => '#/definitions/input_parameters' },
                     output: { '$ref' => '#/definitions/output_parameters' },
-					meta: { '$ref' => '#/definitions/action_meta' },
+          					meta: { '$ref' => '#/definitions/action_meta' },
                     examples: {
                         type: :object,
                         properties: {
                             title: { type: :string },
+                            url_params: { type: :array, items: { type: :integer } },
                             request: { type: :object },
                             response: { type: :object },
+                            status: { type: :boolean },
+                            message: { type: :string },
+                            errors: {
+                                type: :object,
+                                patternProperties: {
+                                    '^[a-z_]+$' => {
+                                        type: :array,
+                                        items: { type: :string },
+                                    }
+                                }
+                            },
+                            http_status: { type: :integer },
                             comment: { type: :string },
                         }
                     },
@@ -99,7 +113,7 @@ DEFINITIONS = {
                 }
             }
         }
-        
+
     },
 
     input_parameters: {

data/doc/protocol.md

@@ -157,6 +157,7 @@ Every action is described as:
         "auth": true|false,
         "description": "Describe what this action does",
         "aliases": ["list", "of", "aliases"],
+        "blocking": true|false,
         "input":  {
             "layout": "layout type",
             "namespace": "namespace name",
@@ -389,12 +390,19 @@ render them according to its syntax.
 
     {
         "title": "A title",
+        "url_params: [ ... array of integers ... ],
         "request": {
             ... a hash of request parameters ...
         },
         "response": {
             ... a hash of response parameters ...
         },
+        "status": true/false,
+        "message": "Message explaining an error if it occurs",
+        "errors": {
+            "<parameter>": [ ... array of errors ... ],
+        },
+        http_status: 200,
         "comment": "Description of the example"
     }
 
@@ -408,13 +416,27 @@ response.
             "input": ... parameters or null ...,
             "output: ... parameters or null ...
         } or null,
-        
+
         "object": {
             "input": ... parameters or null ...,
             "output: ... parameters or null ...
         } or null,
     }
 
+## Blocking mode
+Blocking mode is for actions whose execution takes a long time. Clients can monitor
+progress of such actions and even cancel their execution.
+
+The blocking action returns its result as usual, but provides a unique identifier using
+which clients can check its status via the `ActionState` resource. The state identifier
+is passed through global output metadata in a parameter called `action_state_id`.
+Resource `ActionState` is a part of the API's documentation and is the standard interface
+for browsing and manipulating currently active blocking actions.
+
+An action is blocking if parameter `blocking` in its description is `true` and if
+`action_state_id` is present in its metadata after each call. This allows actions
+to be blocking only when needed.
+
 ## List API versions
 Send request ``OPTIONS /?describe=versions``. The description format:
 
@@ -463,7 +485,7 @@ Example request:
     Content-Type: application/json
     Accept: application/json
     Connection: Close
-    
+
     {
         "user": {
             "login": "mylogin",
@@ -479,7 +501,7 @@ from the self-description.
 Example response to the request above:
 
     Content-Type: application/json
-    
+
     {
         "status": true,
         "response": {

data/doc/protocol.plantuml

@@ -9,14 +9,15 @@ class Meta {
 }
 
 abstract class Authentication {
-	
+
 }
 
 class Basic {
-	
+	description : String
 }
 
 class Token {
+	description : String
 	http_header : String
 	query_parameter : String
 }
@@ -30,7 +31,8 @@ class Action {
 	name : String
 	auth : Bool
 	description : String
-	aliases : list
+	aliases : Array<String>
+	blocking : Bool
 	url : String
 	method : String
 	help : String
@@ -38,8 +40,12 @@ class Action {
 
 class Example {
 	title : String
+	url_params : Array<Integer>
 	request : hash
 	response : hash
+	status : Bool
+	message : String
+	http_status : Integer
 	comment : String
 }
 
@@ -60,7 +66,7 @@ class InputParameter {
 }
 
 class OutputParameter {
-	
+
 }
 
 abstract class ResourceParameter {
@@ -69,14 +75,14 @@ abstract class ResourceParameter {
 }
 
 class TypedInputParameter {
-	
+
 }
 
 class ResourceInputParameter {
 }
 
 class TypedOutputParameter {
-	
+
 }
 
 class ResourceOutputParameter {
@@ -119,7 +125,7 @@ class FormatValidator {
 }
 
 abstract class InclusionValidator {
-	
+
 }
 
 class ArrayInclusionValidator {
@@ -131,7 +137,7 @@ class HashInclusionValidator {
 }
 
 abstract class LengthValidator {
-	
+
 }
 
 class EqualLengthValidator {