API documentation, was Re: Web services revisited

[Chris Travers <..hidden..>]

Just a couple quick notes and questions.

The first is that of course when we started, there was no documentation for SQL-Ledger that was freely available except what I wrote.  Everything that we have has been added since the fork.  I think that some of Nigel's complaints are exactly why a web service is needed.  More on this below.

What we currently have that's in good shape are:

1)  Database documentation  (could be better though if someone wants to help arrange the dia files' diagrams).

2)  Perl API documentation for code that was new in 1.3.  (though this isn't as obvious as to where to look as it needs to be).  All new 1.3 API's are documented, and we are in the habit of documenting API;s as they are created.  For 1.4, I want to organize what documentation we have in this area into a reference manual.  I would also like to ensure that it gets installed as man pages (why I am working on a make install installation).

With web service API's, these too will be documented.

Part of the legitimate reason for Nigel's frustration is that the old SQL-Ledger API approach was pretty brittle and instead of maintaining that we have been trying to move away from it as quickly as we can.  For orders and financial transactions we should be pretty backwards compatible except for authentication (use HTTP basic auth), but these will be moved off to the new framework as soon as we can and then web services will be preferred.  For invoices and orders though this may take a few major versions.

For those doing things like this we can always use samples and writeups.  For people who need help with code they have written, this is a good place to ask.

Anyway, just figured I would throw those things out onto the table.

Best Wishes,
Chris Travers