Re: Web services revisited

[Chris Travers <..hidden..>]

On Wed, May 23, 2012 at 7:59 AM, John Locke <..hidden..> wrote:
> On 05/22/2012 07:06 PM, Chris Travers wrote:
>> On Tue, May 22, 2012 at 12:27 PM, John Locke<..hidden..>  wrote:
>>
>>> Possible Index handler:
>>> GET /rest/1.0/my_company/ar_transactions/?invoice_id=N499216
>> I had a thought about this one.  Suppose we allow a by= field to
>> specify a non-standard id key?  In that case, your URL would look like
>>
>> GET /rest/1.0/my_company/ar_transactions/N499216?by=invnumber
>>
>> The desired result would then be to get a redirect to the the cannonical URL.
>>
>> I am thinking that this avoids issues like:
>> GET /rest/1.0/my_company/customers/A1234/locations/billing?customers_by=meta_number&locations_by=location_class
>>
>> In that case instead you'd do:
>>
>> GET /rest/1.0/my_company/customers/A1234?by=meta_number
>>
>> Capture the redirect address
>>
>> then do
>> [redirect_address]/locations/billing?by=location_class
>>
>> You could then either do a redirect and add the extension or pursue
>> the redirect with the content type header.
>>
>> Note, by would only be valid where the field is a valid secondary key.
>>   The modules would be responsible for enforcing this.
>>
> Hi,
>
> Cool idea, but I'm not sure it's something I would actually use. On the
> client side, I need a unique key for each object -- that might as well
> be the same one as LSMB uses -- and I would rather have a single,
> canonical URL for each object.
>
> So redirects to that are good, if they don't break other expectations.

The obvious use case might be:

ledgersmb/rest/1.0/mycompany/part/912465634532?by=upc

I am thinking in particular an inventory applications might get a lot
of mileage out of such a mechanism.  For example here, if we get a 3xx
response we can just pull the id off the end of the redirect for
purposes of entering inventory.  If we get a 404, we know that this
UPC needs to be attached to a part somewhere.  For example if we get a
404, we might want to search for the part (after requesting user
input) and post the UPC info to that part.  (I am expecting to get
UPC's/EAN's handled under the make/model table in 1.4, so partnumber
is dependent on UPC, but each part may have several UPC's)

Another use case might be if I open up some part of web services so
you can import the AR invoices I send you as AP invoices in your
system.  So you get a PDF invoice.  You enter the invoice number, and
it sends back a redirect to the cannonical URL, and your system
imports it.  You can then verify that they match before submitting.
Of course a collection might work as well here, but it would not be as
graceful I think, in the UPC case above.

>
> And implementing a service, it's easy to assume either individual
> objects if I have what looks like a resource path (e.g. with an id) or
> collections otherwise.
>
> So I would say this is fine, but not something high on my list or would
> likely use. It's just as easy to do an index lookup with the search
> parameters for other keys.
>
> The biggest question I would have would be around the defaults. For
> example, on the AR transactions screen, a search by default only shows
> open invoices. However, a search by invoice number does return closed
> invoices even when the "closed" button is unchecked. This is a very nice
> feature for usability, but it's also somewhat unexpected. Should either
> document these exceptions very clearly, or remove them from the web
> service -- perhaps default to returning all invoices, and force a web
> service to specify open if that's all they want?

Well, with no boxes checked, the AR report returns no invoices.  By
default the open box is checked and the closed box is not.  I would
expect that we'd have to have some default parameters for web services
too, and that these would have to be different since the use cases and
feedback are different.

For example, when doing a search, I would prefer to default to all but
exclude ones based on input.  So here I would think a more natural way
to do a web service would be:

....ar_transactions/?exclude=open+closed

and this way we get back to an empty collection excluding open and
closed invoices.....

As far as posting/retrieving collections, where the data is simply
tabular, I am planning on allowing tabular-format uploads, such as
CSV, ODS, and eventually Excel.  I figure a lot of the logic can be
re-used for allowing CSV, XLS, and ODS uploads from the web app as
well.

Best Wishes,
Chris Travers