Re: Proposal: Web Services API

[Chris Travers <..hidden..>]

On Tue, Oct 25, 2011 at 1:38 PM, John Locke <..hidden..> wrote:
> Hi,
>
> Erik and I were just chatting on IRC about web services. I recently
> updated our in-house management system to generate new invoices in LSMB,
> and it's a pain in the butt to do -- the current process looks like this:
>
> 1. Hit the Login page with username/pw, store session cookie
> 2. Post some minimal detail to is.pl - customer name/entity_credit_id,
> part numbers/qty, action=update
> 3. Parse the response, scrape all the form fields out and merge their
> values with the items we want to post -- and in 1.3 make sure to update
> form_id to get past the anti-csrf protection
> 4. Post the resulting data to is.pl with action=post

Yeah, that's sub-optimal on so many levels.

>
> ... and then if we want to also send an email, essentially repeat the
> last couple steps to send the email out to the billing address.
>
> It sounds like adding a good web service api would help this project for
> at least a few of us -- but probably help get far more wide-spread
> adoption.

Jason Rodrigues was working on this before he dropped off the project.
 His work could be used as a basis for reviving this and is in svn
(but have to check where).

>
> At Freelock, we do a substantial amount of web services work, both
> creating servers and consuming them as clients. I've come to really
> favor REST-based, resource-oriented APIs that use HTTP verbs to mean
> something. I'd like to propose building a REST interface that can
> interact with the data on the server.

That's exactly where the partial work that was done was going.
>
> Is this something that Moose will get us without much work?
>
> If not, I'd be happy to contribute code to serve this purpose, if I can
> find somebody to sponsor the work. And I'll definitely provide feedback
> if anyone wants to take this on themselves.
>
Any contributions in this area are welcome.  I'd suggest starting with
a review of what we have so we know what's involved in doing it.
>
> What I'd like to see is basically an API that has a specific URI for
> each resource. For example, an invoice #456 might be referenced at:
>
> http://myledgeraddress.com/store/invoice/456
>
> A simple GET on that address would check for authorized access, and then
> retrieve the invoice in a form requested by the client. I generally set
> up services to accept a content-type header to specify xml, json, html,
> csv, etc -- and allow it to be overridden by a parameter in the query
> string.
>
> A PUT on that address with an updated object in the body would update
> the object, again based on authorization. (I'm thinking to add payment
> to an invoice).
>
> A DELETE on that address would delete (almost certainly dis-allowed on
> this type of object).
>
> POST is used to create new objects, or do particular data-changing
> actions on an object or in the system.
>
> GET would also accept a variety of parameters, providing a built-in
> search to get a collection of objects --
>
> GET http://myledgeraddress.com/store/invoice/?eca_id=334&open=any
> GET
> http://myledgeraddress.com/store/customer/?start_date=2011-01-01&start_date_oper=gt
>
>
> For implementation, this should be pretty easy to provide some sort of
> request handler and load up the new objects that Chris has created, do
> the appropriate changes, and save. The old code is obviously much harder.

Reviewing Jason's code (see the LedgerSMB/RESTXML directory), it's all
against old code, and some of it is quite outdated.  However it might
be useful as a base.
>
> Perhaps we can start with the new entities, customers and vendors that
> have already been done, and add more of the accounting objects as they
> get rewritten?

Hope this helps,
Chris Travers