RFC: API layers

[Chris Travers <..hidden..>]

This writeup is a general proposed framework for thinking about the
LedgerSMB API as it develops on new code.  Each section includes use
cases as I see them, as well as security considerations and limiting
factors.

This is my current vision for LedgerSMB as a platform.   It is
essentially a discussion draft.

1)  DB-storage-level API (stable table structure within a stable branch)
Use cases:  Trigger-based integration with other applications
co-existing in the same database
Security considerations:   This should be used for READs only, and never WRITEs.
Limitations:  Security, subject to significant change between major versions

2)  Encapsulated DB API (stored procedures and views)
Use cases:  Thick clients running on the internal company network.
Security Considerations:  Given the importance of the database, one
would not want to expose this over the public internet (hence either
internal network or vpn)
Limitations:  Security

3)  Structured Data layer of API (private API layer not directly
exposed, basis for higher levels)
 Presumably each object would be able to define eventually a nested
and a flat representation, and modules could be plugged in to parse
and hand off.  This API could be used by developers to create
additional ways of interacting with LedgerSMB.
Use cases:  Thick clients running external to company network, server
to server integration, highly asynchronous calls
Security Considerations:  Some API calls may not be safe over the
internet.  I think we need some level of control over what interface
allows what and to give this to the administrator.

4a) RESTful Web Services:  Stateless, simple resource/document handling
No session handling, user auth in each request.
Use cases:  loosely coupled server-server and client-server
integration for atomic requests.  For example timecard entry, or parts
lookup.
Security considerations:  Long-run must be able to be limited to
client by API.  This could be done cryptographically or otherwise.
Also such web services probably should not post financial transactions
to the books without human review through other applications.
Other limitations:  This would not be suitable for tightly bound
workflows, such as batch payment processing.

4b)  Document processing infrastructure:  Complex collections of
objects in a single document
Use cases:  EDI processing and the like. Mostly for highly
asynchronous processing
Security considerations: Documents must come from trusted sources.
Automated interfaces should not post financial transactions to the
books without human review.
Other limitations: some developer effort would be required

4c-z) Stateful wrapping of structured data apis, such as via XMPP,
Perl Object Environment, node.js,etc.
Use cases:  Complex, interactive use cases not covered under the above.
Security considerations:  Depends on application
Other limitations:  Adds complexity and latency to systems, so not
usable where these are critical (POS terminals and the like).