Re: [Ledger-smb-devel] Web Services API: URL naming proposal
Sorry for the delay in reply... been off sick, back now On 18/11/11 13:52, Chris Travers wrote: Figure i will wade in here. Hopefully others will follow. 1. The base address mentioned by John was something like 'http://myledger.com/ledgersmb/store/'. However, if we assume that the login address of the 'http://myledger.com/ledgersmb/login.pl', there may be an issue with the '/store/' part. Can we support that on all servers, or does that not matter? Do we allow '/store.pl/' or any other URL? ie. do we not consider that part of the API, other than that it is a prefix? i don;t think that would be a problem. I don't like store though because it is pretty unclear. I would suggest a base path of: http://myhost/ledgersmb/webservices/company_name/ Then http auth headers can be used for the rest. Why wouldn't we use http auth headers to select the company (I prefer company too, rather than store). Just asking, I don't have strong views either way. 2. Since companies are separate databases, where do we put the name of the company in the URL? prefix/store.pl/company/etc...? What do you think of the above proposal? Are there other items to consider before we go to specify the web service behaviour of our natural/legal entity storage paradigm? I think the key issue is designing a logical entity hierarchy for things. Otherwise I don't see any other issues that will come up in this preliminary stage. Agreed. -- All the data continuously generated in your IT infrastructure contains a definitive record of customers, application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-novd2d ___ Ledger-smb-devel mailing list Ledger-smb-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel
[Ledger-smb-devel] Wish - Notes field for Bank accounts
Hi, I am playing with the 1.3.6 (r4018) in my server and I recorded a new customer into ledgersmb. I can add bank accounts, but it would be useful to create a note for each bank account. The sample: BIC/SWIFT Code Account number Notes HUCIT 12345678-12345678 CityBank, EUR HUCIT -12345678 CityBank, HUF HUBUD - BudapestBank, USD I think you can understand, why should be it a useful. What do you think? Thank you, István -- All the data continuously generated in your IT infrastructure contains a definitive record of customers, application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-novd2d___ Ledger-smb-devel mailing list Ledger-smb-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel
Re: [Ledger-smb-devel] Web Services API: URL naming proposal
I think John's points here raise some important questions I'd like to raise here for further discussion: On Sun, Nov 20, 2011 at 9:30 AM, John Locke m...@freelock.com wrote: Hi, all, Been quite swamped with work recently, sorry for the delay. Having just designed a REST API for a client, have some fresh perspective. Below... I'm starting to like /api/ or /rest/ for the path that identifies the web service. And also adding an API version number to that endpoint, so that it becomes possible to change the API in the future while still maintaining an old version (should the organization wish to...) That's not a bad idea. On authentication, yes we can use http auth headers, but do we want to explicitly require a session token, too? We're starting to delve into OAuth -- which adds a layer of complexity but also can take away the need for the remote system to collect the password at all. This seems like a good option to support. A couple questions: 1) For an API aimed at other applications, why have a session token? What does it buy us? In the main application we use a session token to enforce a full round trip in some cases (XSRF prevention), and to handle discretionary locking in long workflows (actually more properly, timing out of such locks). Neither of those general requirements apply to a job from an OS Commerce installation which is feeding sales orders into LedgerSMB. 2) How does OAuth affect our ability to pass through credentials to the database? Or would a web services handle have to do its own authentication? 3) Does the added complexity make sense with general use cases? I am assuming we are primarily interested in a web services API for server-server integration since a piece of software used primarily by the end user would be more likely to just call the db-level API (which would provide greater control over db transactions, and the like than one would get from a web services interface)? 2. Since companies are separate databases, where do we put the name of the company in the URL? prefix/store.pl/company/etc...? What do you think of the above proposal? I suggest we include the company in the body of the login, and then it's represented in the session cookie. If an external application needs to work with multiple companies, it can manage multiple session ids. This is contrary to REST ideals, correct? Not that departures from that are necessarily out, but I would prefer to see some justification for the added complexity of requiring state handling and cookies. Also I suspect (though I will defer to others here) that debugging an incorrect company name may be easier if that shows up in the url in the access logs. So one thing is identifying supported formats for the data -- I suggest we support JSON, multi-part form (e.g. URL encoded like a regular form post) that returns HTML, and some relatively simple XML. Type can then be specified via Accept header, and also by adding a suffix to the URL. For example: http://myhost/ledgersmb/api/1.3/customer/224.json http://myhost/ledgersmb/api/1.3/customer/224.xml But those formats are not all entirely equivalent are they? I JSON and XML are close and could be easily supported together, but they allow nested data structures while form submissions are flat, right? If we support form type submissions as a full API, then this means we have to choose between added maintenance of two very different data representations and forcing the xml and json to the least common denominator, correct? This becomes a bigger deal as time goes on and more stored procedures expect some form of nesting in argument lists. This being said, I like the use of extensions here, and I think the overall idea is sound. Now, if we are to do this, I would suggest we go with a plugin model for file types, i.e. require a parser which converts the incoming file into a Perl hashref, so that we can add other file types if we ever have to. That way if someone really needs plain form submission handling we have an avenue to support that in the future, even if the API might be more complex in order to handle lit. POST/PUT type should get specified by Content-Type header. I suggest we start with the base entity structure that mostly maps to the database structure, then add sugar path shortcuts to make this easier to use. e.g. all of the below might map to the same item: http://myhost/ledgersmb/api/1.3/entity?eca=224 http://myhost/ledgersmb/api/1.3/entity/eca/224 http://myhost/ledgersmb/api/1.3/eca/224 http://myhost/ledgersmb/api/1.3/entity/eca/customer/224 http://myhost/ledgersmb/api/1.3/customer/224 http://myhost/ledgersmb/api/1.3/customer?meta=557 (which might redirect to the actual eca id) Ok, if you mean the structure of the db api then I would entirely agree (I think the physical structure of the DB is beside the point). So let's do this: 1) A flat namespace for primary types/identifiers below the API base URL 2) Open
Re: [Ledger-smb-devel] Web Services API: URL naming proposal
John == John Locke m...@freelock.com writes: John I'm starting to like /api/ or /rest/ for the path that John identifies the web service. And also adding an API version John number to that endpoint, so that it becomes possible to change John the API in the future while still maintaining an old version John (should the organization wish to...) John On authentication, yes we can use http auth headers, but do we John want to explicitly require a session token, too? We're John starting to delve into OAuth -- which adds a layer of John complexity but also can take away the need for the remote John system to collect the password at all. This seems like a good John option to support. John So: I would suggest for login, something like: John POST http://myhost/ledgersmb/api/1.3/user/login +1! Include api and the version number. This is common in the rails community too. Sometimes v1.3 if it makes object naming easier. -- ] He who is tired of Weird Al is tired of life! | firewalls [ ] Michael Richardson, Sandelman Software Works, Ottawa, ON|net architect[ ] m...@sandelman.ottawa.on.ca http://www.sandelman.ottawa.on.ca/ |device driver[ Kyoto Plus: watch the video http://www.youtube.com/watch?v=kzx1ycLXQSE then sign the petition. -- All the data continuously generated in your IT infrastructure contains a definitive record of customers, application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-novd2d ___ Ledger-smb-devel mailing list Ledger-smb-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel
Re: [Ledger-smb-devel] /setup.pl - erorr in httpd error log - ID: 3440417
Hi Harvard; On Sun, Nov 20, 2011 at 8:30 PM, Håvard Sørli hav...@anix.no wrote: As a quick explanation, changed that to wontfix because at present it's not really optimal behavior but not really a bug per se. It adds some noise to the log files which are helpful in some cases however because: 1) This is a rare task 2) The info in the logs is sometimes helpful 3) While the behavior is suboptimal it isn't really immediately obvious that there is more correct behavior. I am suggesting it's not a bug and can't simply be fixed. Hence more discussion and the idea that hopefully we will come to a resolution as to what we want to do down the road to change this. Thanks for an explanation of the error. But, could we do this a little better ? (I hope am not the first new user that read logs, and post error's) Absolutely it could be done better. I can think of any of a number of ways it could be done better. For example we could log such messages as DEBUG messages or WARNs Or we could bracket in the log files as you suggest. We could even combine these approaches or prefix such warnings with something that identifies what is going on. Three more points: 1) Patches on this matter would probably be accepted as bug fixes even in the stable branch 2) On my side I see this as a very low priority. 3) I am happy to write up a bug report if nobody beats me to it which reflects whatever consensus evolves on this list. Such a bug report would be a low priority one. I have changed the resolution to Later Best Wishes, Chris Travers Best Wishes, Chris Travers -- All the data continuously generated in your IT infrastructure contains a definitive record of customers, application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-novd2d ___ Ledger-smb-devel mailing list Ledger-smb-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel
Re: [Ledger-smb-devel] Web Services API: URL naming proposal
Hi, On 11/20/2011 04:24 PM, Chris Travers wrote: I think John's points here raise some important questions I'd like to raise here for further discussion: On Sun, Nov 20, 2011 at 9:30 AM, John Locke m...@freelock.com wrote: On authentication, yes we can use http auth headers, but do we want to explicitly require a session token, too? We're starting to delve into OAuth -- which adds a layer of complexity but also can take away the need for the remote system to collect the password at all. This seems like a good option to support. A couple questions: 1) For an API aimed at other applications, why have a session token? What does it buy us? In the main application we use a session token to enforce a full round trip in some cases (XSRF prevention), and to handle discretionary locking in long workflows (actually more properly, timing out of such locks). Neither of those general requirements apply to a job from an OS Commerce installation which is feeding sales orders into LedgerSMB. Well, think mobile app for a minute, or desktop app. There may well be many cases where you want round trip, transaction handling, and anti-XSRF (or at least anti-replay) prevention. That is what I hate most about SOAP -- having to do multiple calls and manage state. But to a certain extent, it seems unavoidable. It's probably not a big deal to make a remote application pass the company in the URL (instead of in a login session), but slightly easier I would think to omit (in client implementation), to simply pass in with authentication. In many ways, the web application front end is a model for other applications that might call the web service -- ideally everything in the web application should be reflected in the web service. In my experience, most web services still do make use of session handling, it's not at all an uncommon approach. 2) How does OAuth affect our ability to pass through credentials to the database? Or would a web services handle have to do its own authentication? I haven't done this in detail yet, but my understanding is that the client application must register with the web service, and the user then authenticates directly with the web application out of band, with the client application token. Probably more complex than necessary for most installations. But we should make it possible to plug in this type of authentication, should somebody care to implement. Oh yeah, forgot that we use these credentials directly to access the database. Yeah, that would probably necessitate the actual credentials being stored in the session -- not ideal. 3) Does the added complexity make sense with general use cases? I am assuming we are primarily interested in a web services API for server-server integration since a piece of software used primarily by the end user would be more likely to just call the db-level API (which would provide greater control over db transactions, and the like than one would get from a web services interface)? Well, server-to-server is certainly the first step. And easiest to adapt to just about any interface we develop. But today we're doing most web services for iOS or Android apps. Think about the POS or an inventory module being available as an app for an Android phone. The recent thread by a Google engineer praising Amazon for making everything an API applies here. If you haven't read it: https://plus.google.com/112678702228711889851/posts/eVeouesvaVX 2. Since companies are separate databases, where do we put the name of the company in the URL? prefix/store.pl/company/etc...? What do you think of the above proposal? I suggest we include the company in the body of the login, and then it's represented in the session cookie. If an external application needs to work with multiple companies, it can manage multiple session ids. This is contrary to REST ideals, correct? Not that departures from that are necessarily out, but I would prefer to see some justification for the added complexity of requiring state handling and cookies. Well, yes, it is contrary to REST ideals -- but there's definitely room in REST for actions as well as resources. And I was thinking while writing this up about what might be an effective way of supporting transactions -- complete with begin transaction, commit, and rollback posts. I'm not entirely opposed to putting the company in the URL -- it's certainly a viable approach. However, given the complex structure of entity/eca/customer objects alone, having the ability to wrap that in a transaction might be desirable... And I think leveraging the current session handling in the app can reduce opening up new security vulnerabilities. Not suggesting we build anything new for this, just use what we've already got. Also I suspect (though I will defer to others here) that debugging an incorrect company name may be easier if that shows up in the url in the access logs. This could easily be printed in a debug log. Not
