Re: Web services revisited

[Chris Travers <..hidden..>]

On Mon, May 21, 2012 at 4:50 AM, Tone-irene Andersen
<..hidden..> wrote:
> Hi..
>
> I think it would be easier to just have a one file api and not so many urls
> to take care for.
>
> Example: ledgersmb?a=poi&args
>
> where a describe the function. also possible to allow sub commands.

One thing to keep in mind here is that a lot of us have spent a lot of
time professionally doing systems integration work, and that this sort
of integration is the target of the web services.  There are a lot of
cases that what looks simple in this case can be very complicated in
practice, particularly where complex data is exchanged.

>
> If you make something that hard your gonna have a system that noone of the
> "simple" people can use in the end because it require a ledgersmb programmer
> to make nessecary programs to manage the api calls for you.

Two things to keep in mind.  Some things are simple and yet cumbersome
at first until you get the hang of them Think VIM as a text editor.
If you are using something other than VIM or EMACS for coding and
spending more than a few hours a week coding, you need to switch as
painful as it is at first.  This will save you a lot of time later.
There is, however, a learning curve.  After a few hours of learning
it, though, your productivity will be significantly better and pretty
soon you will more than have made up for the effort.

It's the same way here.  The goal of this exercise is to make tools
for system integration that people can be productive using.  This
means using things that are conceptually simple once you learn them,
and not sacrificing simplicity in the way it is actually used in order
to avoid a learning curve.  Indeed, I would suggest that if you
actually look at examples, it is clear that this *is* simpler.  In
your proposal we have something like:

ledgersmb?a=get_customer&id=23&format=xml&company=mycompany

The same would be a GET request to:
ledgersmb/rest/1.4/mycompany/customer/23.xml

Now consider the two.  On the first I have to read it carefully to see
what the format is.  In the second, it's obvious.  The second also
emphasizes the relationship between the two.  Once you are used to it,
it is quite a bit simpler.

But now suppose we want to overwrite customer 23 with a new record
which includes also a vendor credit agreement too, a bank account and
more.

In this system we create an XML file lilke:

<?xml version="1.0" ?>
<customer>
   <company legal_name='Test Company' country_code='US' taxnumber='12345'
             entity_class='2' />
   <eca meta_number='C123' pay_to='Examples, Inc' description='Example'
        start_date='2011-01-01' credit_limit='500' currency='USD'
        terms='30' arap_accno='1200' cash_accno='1060' language='en_US'
        entity_class='2'>
       <location class_id='1' line_one='103 Park Road' city='Red City'
                 state='Washington' mail_code='97432' country_code='US' />
       <contact class='email' description='Accounts Payable'
                contact='..hidden..' />
       <note>This is a note about the customer account.</note>
   </eca>
   <eca meta_number='V123' pay_to='Examples, Inc' description='Example'
        start_date='2011-01-01' credit_limit='500' currency='USD'
        terms='30' arap_accno='2100' cash_accno='1060' language='en_US'
        entity_class='1'>
   </eca>
   <note>This is a note about the entity and will show up on both accounts.
   </note>
   <bank_acct bic="12435655" iban="3245431235" />
</customer>

We then issue a PUT http request to the same URL above.  We are saying
"put this resource there!"  And the system does so.

Now if we try to do the same thing with a single HTTP query and args,
we get this (imagine it as all one line):

ledgersmb?a=save_customer&legal_name=Test+Company&country_code=US
&taxnumber=12345&meta_number_1=C123&pay_to_1=Examples,+Inc.&
description_1=Example&start_date_1='2011-01-01'&credit_limit_1=500&
currency_1=USD&terms_1=30&arap_accno_1=1200&cash_accno_1=1060&
language_1=en_US&entity_class_1=2&entity_class=2&eca_count=2&
note_1_1=This+is+a+note+about+the+customer+account.&class_id_1_1=1
line_1_1=103+Park+Road&city_1_1=Red+City&state_1_1=Washington&
mail_code_1_1=97432&country_code_1_1=US&locations_count_1=1&
contact_class_1_1=email&description_1_1=Account+Payable&
contact_1_1=..hidden..&contact_count_1=1&
meta_number_2=V123&pay_to_2=Examples,+Inc.&description_2=Example&
start_date_2=2011-01-01&credit_limit_2=500&arap_accno_2=2100&
cash_accno_2=1060&;anguage_2=en_US&entity_class_2=1&
note_1=This+is+a+note+about+the+entity+and+will+show+up+on+both+accounts.
&note_count=1&note_count_1=1&note_count_2=0&location_count_2=0&
contact_count_2=0&iban_1=3245431235&bic_1=12435655&bank_count=1

That doesn't seem simpler and it is certainly a lot more complex to debug.

So suppose we try to break this up into different requests.  By my
count you'd have 8 requests, and a fialure on request 7 would mean
you'd have to correct what was entered into your database, and you
have to capture data and organize it between the stages.  This is of
course less of a concern for customer data than it is financial
transactions.....

Anyway the states look like:

1)  Save the company, grab the entity_id
2)  Save the first eca grab the id
3)  Save the first location for the first eca
4)  Save the first note of the first eca
5)  Save the first contact of the first eca
6)  Save the second eca, attached to the same entity id as the first
7)  Save the company-level note
8)  Save the bank account

And the eca save lines look like:

ledgersmb?a=eca_save&meta_number=C123&pay_to=Examples,+Inc.&
description=Example&start_date='2011-01-01'&credit_limit=500&
currency=USD&terms=30&arap_accno=1200&cash_accno=1060&
language=en_US&entity_class=2&entity_id=234


Still, long and complex, and hard to debug.

Best Wishes,
Chris Travers