[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: API documentation, was Re: Web services revisited

On 22/05/2012 16:30, Chris Travers wrote:
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.

And let me quickly say that I enormously appreciate the work that the developers are doing

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).

Can you point me at this please?

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).

Is this documented in the code or elsewhere?
With web service API's, these too will be documented.
Wonderful.... and I really mean it.

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.

I'm really looking forward to the new framework. My fingers are becoming deformed through keeping them crossed that my current ramshackle arrangements will keep going.

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.

Many thanks again