Re: Web services revisited

Hi..

I just wanted to say i can help write, problem is. I dont have a vast experience with ledgersmb. I know how to login and im getting breathdeprived after that. It just natrually stop my willing to help due to my experience.

I want to have a article system on the site so we can add categories and alot of articles about everything for ledgersmb. It would be easier to have one of the devs write the core of everything, and the rest of us to make it pretty Smile

Regards,

Tone Irene Andersen

From: Nigel Titley

Sent: Tuesday, May 22, 2012 3:27 PM

To: ..hidden..

Subject: Re: [Ledger-smb-devel] Web services revisited

I have to say I agree with both of you.

Chris' point is valid. There will be a steeper learning curve but the final result will be much cleaner and easier to use.

However, Tone-Irene has an excellent point and one that I can really feel for (having written at least a partial bridge between LedgerSMB and Oscommerce). The API documentation for ledgersmb is old, inaccurate and in most cases non-existent. The code, until you get some idea of what is happening, is opaque and sparsely commented.

Please, please, please can we have some documentation for the API, preferably at the beginning rather than the end. A good, well documented API would do more than anything else to help push ledgerSMB into the mainstream. And if you are doing the API design properly it should fall out of the design. And if we get some documentation, we can start to build applications in parallel with the API, which means that more testing will get done, which will improve the design.

And just to give you an idea of what services I really need at the moment

Sales order creation
Parts creation
Customer creation
Invoice generation

The first three I've managed to get working using the existing, almost completely undocumented API, the last I have a member of staff at least half time on doing manually. If it is possible to work on these services then I'll be able to rewrite the Oscommerce bridge properly... and this will be a powerful incentive for folk to use ledgersmb rather than Quickbooks.

Thanks

Nigel

PS While we're talking about documentation. I've made a standing offer to write VAT reports for use in Europe, but I can't do this until I've got some documentation on writing reports.

On 22/05/2012 13:44, Tone-irene Andersen wrote:

Hi..

Yes Chris i get your point, but ive yet to find a manual to install ledgersmb probably on debian on the website. All the documentation is outdated and from old versions.

Im afraid that this will happen with this api also, if you have no documentation it will hard for people to understand.

On a sitenote, whats the 23.xml for? How will we find the correct customer number? What if we dont know the number?

There is alot of factors to API's. I rather want a API thats easy to use, understandable and have the updated documentation for it rather than some api developers make which have no documentation except "ask experts".

All i say is. we rather want a great api than a api that dont work.

Regards,

Tone Irene Andersen

On 05-22-12, Chris Travers mailto:..hidden.. wrote:

On Mon, May 21, 2012 at 4:50 AM, Tone-irene Andersen
mailto:..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
------------------------------------------------------------------------------
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

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