Web services revisited

[Chris Travers <..hidden..>]

Hi all;

I am just about to start on  a web services wrapper for 1.4.
Reviewing the past discussions on this, I want to just submit my
proposal for review before I get started.  What I expect to start on
is very simple.


URL would be of the format of:

[lsmb_base_url]/rest/company_name/[major version]/[top level
object][/id][/resourcetype/][.extension]?argstring


"rest" would be a reserved word and not usable for any later part of
the API.  I.e. it can never be a valid object name, resource type, id,
or object class name.  We'd use it to automatically determine where
the path starts.

There would be two additional directories of objects here.
LedgerSMB/REST_Formats/*.pm would be to handle formats (XML, JSON,
etc). LedgerSMB/REST_Objects/*.pm would provide handling of the actual
top-level objects.  LedgerSMB/REST_FORMATS/DEFAULT.pm would be
reserved for handling standard form-multipart post data.  Right now it
would just throw an error.

Each format handlerwould have just two methods:  from_input() and
to_output() which would encode or decode the format.....

Each top-level class would need to provide the following methods:

* GET, POST, DELETE, and PUT would handle cases where no resourcetype
is present.  Typically this would be search, retrieve, or post
routines.
* One method for each resourcetype, suffixed optionally with _GET,
_POST, _DELETE, or _PUT.  If a suffixed method does not exist, the
resourcetype name would be used as the method name.

My thinking is to have the flow go as follows:


Main handler parses request, organizes it into a hashref with the
following components as applicable:

dbh (database handle)
class_name
id
resourcetype
method
payload
format
args

The payload would then be handed off to the format handler and reset
as a hashref returned from the from_input routine.

The handler would then use the appropriate class, and dispatch as follows:

If resourcetype is present, try to dispatch to resourcetype_method, if
that fails dispatch to resourcetype.  If resourcetype is not present,
dispatch to method.

Take hashref that is returned and hand back to the format handler for
it to be run through the to_output function, and then send this back
to the browser.

What do people think?

Best Wishes,
Chris Travers