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.
¬e_count=1¬e_count_1=1¬e_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
------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's
security and
threat landscape has changed and how IT managers can
respond. Discussions
will include endpoint security, mobile security and the
latest in malware
threats.
http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
_______________________________________________
Ledger-smb-devel mailing list
..hidden..
https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel