[pve-devel] r4982 - pve-common/trunk

[svn-commits at proxmox.com]

Author: dietmar
Date: 2010-08-12 12:17:08 +0000 (Thu, 12 Aug 2010)
New Revision: 4982

Modified:
   pve-common/trunk/README.dev
Log:
more docu


Modified: pve-common/trunk/README.dev
===================================================================
--- pve-common/trunk/README.dev	2010-08-12 11:48:51 UTC (rev 4981)
+++ pve-common/trunk/README.dev	2010-08-12 12:17:08 UTC (rev 4982)
@@ -5,7 +5,7 @@
 =============
 
 We decided to change our SOAP API (1.X) and use a REST like API. The
-concept is described in [1] (Ressource Oriented Architecture
+concept is described in [1] (Resource Oriented Architecture
 (ROA)). The main advantage is that we are able to remove a lot of code
 (the whole SOAP stack) to reduce software complexity.
 
@@ -20,10 +20,10 @@
 JSON and JSON Schema
 ====================
 
-We use JSON as data format, because it is simple and parseable by any
+We use JSON as data format, because it is simple and parse-able by any
 web browser.
 
-Additionaly, we use JSON Schema [2] to formally describe our API. So
+Additionally, we use JSON Schema [2] to formally describe our API. So
 we can automatically generate the whole API Documentation, and we can
 verify all parameters and return values if they conform to the schema.
 
@@ -36,13 +36,69 @@
 A small utility called 'pvesh' exposes the whole REST API on the command
 line.
 
-So here is a sumary of the advantage:
+So here is a summary of the advantage:
 
    - easy, human readable data format (native web browser format)
    - automatic parameter verification (we can also verify return values)
    - automatic generation of API documentation
    - easy way to create command line tools (using same API).
 
+API Implementation (PVE::RESTHandler)
+===================================
+
+All classes exposing methods on the API use PVE::RESTHandler as base class.
+
+  use base qw(PVE::RESTHandler);
+
+To expose methods, one needs to call register_method():
+
+  __PACKAGE__->register_method ($schema);
+
+Where $schema is a PVE method schema a describe in PVE::JSONSchema. It
+includes a description of parameters and return values, and a
+reference to the actual code
+
+__PACKAGE__->register_method ({
+    name => 'echo', 
+    path => 'echo', 
+    method => 'GET',
+    description => "simple return value of parameter 'text'",
+    parameters => {
+	additionalProperties => 0,
+	properties => {
+	    text => {
+	    	 type => 'string',
+	    }	  
+	},
+    },
+    returns => {
+	type => 'string',
+    },
+    code => sub {
+	my ($conn, $resp, $param) = @_;
+
+	return $param->{text};
+    }
+});
+
+The 'name' property is only used if you want to call the method
+directly from Perl. You can do that using:
+
+  print __PACKAGE__->echo({ text => "a test" });
+
+We use Perl's AUTOLOAD feature to implement this. Note: You need to
+pass parameters a HASH reference.
+
+There is a special helper method for command line tools, where you
+want to pass arguments as array of strings:
+
+  my $args = ['-text', 'a test"];
+  print __PACKAGE__->cli_handler('echo', $args);
+
+Note:: This uses Getopt::Long to parse parameters.
+
+The 'path' property is used by the HTTP servers to setup the URL.
+
 References
 ==========
 [1] RESTful Web Services