On the subject of a hypothetical REST API: On Sunday, May 27, 2012 10:01:37 PM UTC-7, Tim Crews wrote: > > I know that some people get passionate about REST design principles. > > OK, I confess. I'm one of these people.
I've been thinking of the role of the APIs (both REST and Python) within the context of the organizational problems that some Ledger users need help with, especially the requirement to provide accountants with a graphical user interface other than Emacs to modify Ledger data. I think this has several implications that would affect the functionality exposed by any proposed API. ------------------------------ This point applies to both the hypothetical RESTful API and the existent Python API: To solve the "accountants don't like Emacs" problem, we need GUI applications (and, by extension, underlying APIs) that allow ledger data to be written and modified. I understand that this would be a big change to the ledger application, and maybe even the ledger philosophy, but I can't think of a way around that. Even for people (like me) who practically live in Emacs, there are many desirable automated processes that need to be able to write ledger data (for example importing transactions from downloaded bank statements into Ledger.) Currently, many ledger users are brewing their own ad-hoc scripts to accomplish this. This repetition of work is wasteful, and doesn't benefit the ledger community. I have put hundreds of hours of work into my own system built around ledger -- and none of you have benefited from it. If I understand correctly, the only code in the Ledger project that modifies journal files is Emacs Lisp code. If it is very important to maintain the read-only purity of the Ledger command-line application, perhaps it would be possible to produce a separate application that performed ledger journal file writes. But the ledger C++ source code base already knows so much about the ledger journal file format, it would be a shame to re-implement the wheel, and I think a unified read/write API would be much more usable. Presumably, a GUI application would be presenting lists of posts that meet certain criteria. Users would then want to continue that same interaction to modify those posts. If the ledger application/API already has a reference to the affected post, it would be a shame to require a separate application to find the same post for the purpose of modifying it. And how would it find the post, anyway, without repeating all of the work that ledger already did? ------------------------ Without assuming that I've convinced anyone, for the purposes of discussion I will proceed with the premise that write access would be added to ledger, and that this write access would be exposed at the API level. A pure Python application could modify posts and transactions directly through the corresponding Python API object references, so there are no big conceptual problems there. A RESTful API would be more problematic, though. One important aspect of resource-oriented design (as espoused in Richardson's and Ruby's book "RESTful Web Services") is that resources need persistent identifiers. I think that might be a source of friction between a RESTful API to Ledger and the current implementation of Ledger. The C++ implementation and the Python bridge that is laid over it do expose objects corresponding to individual posts and transactions. In the C++ code, I notice that each such item is descended from an item_t class, and the item_t class does implement an id() function, which returns either the item's UUID tag (requiring specific markup in the ledger journal file), or a number based on the position of the item in the journal file. The problem with using the position as an identifier at the REST API level (for example, /ledger-api/journals/some-journal-id/posts/some-post-id/xacts/some-xact-id) is that the IDs would change every time the ledger journal file was updated, which would make them unsuitable as REST resource identifiers, at least by my ivory-tower standards :^) . If the RESTful API is only ever going to be used to query the ledger data (as is currently the case for the ledger application itself), then I guess there would not be any services that would *need* to identify these resources. But if the RESTful API is going to provide any services that manipulate and modify the results, then the items that comprise those results will need persistent identifiers. ------------------------ Well, I suppose I've said way more than enough by now. Since I haven't received any feedback yet, I might be in danger of polluting the mail list. I'll lay off until I hear otherwise. Tim Crews
