Re: [search-ws] [Issue] Encode operation in URL not URL option

[Farrukh Najmi <farrukh@wellfleetsoftware.com>]

Hi Ashley,

Thank you for the good questions.
Please see response inline below...

Ashley Sanders wrote:
> Farrukh,
>
>
> >   * Avoid using URL options whenever information can be endcoded in
> >     URL (operation=)
>>    * Avoid using verbs when we can use nouns (replace scan with terms)
>
> Can you explain please what the above actually means? As far as I can
> tell from your examples, all you have done is convert
>
>     /sru?operation=scan
>
> to
>
>     /sru/terms?
>
> And converted
>
>     /voyager?operation=search
>
> to
>
>     /voyager/search?

That is correct that what I propose is a fairly simple and seemingly 
insignificant change (one that implementations should have no problem 
absorbing).

>
> Why is this an improvement? What are the advantages of encoding
> urls your way as opposed to the old way?
It has to do with whether we aim for our HTTP GET binding to be as 
RESTFul as possible.

REST is a resource oriented architecture (ROA) while SOAP is a service 
oriented architecture (SOA).
This means that a RESTful interface defines resources (nouns) rather 
than operations (verbs). A resource is addressable by a unique URI (URL 
in HTTP). The resource URI should reflect the containment hierarchy for 
the resource.

Thus in REST whenever possible one should model resources and not 
operations.

At times this is not easy. For example, it is not easy to model a search 
as a resource. In such cases REST suggests to model an algorithm that 
may be invoked via a URL that includes algorithm parameters. This 
"algortithm" special case sure sounds like an operation but its quite a 
bit simpler since you simply have to identify the algorithm and supply 
its parameters.

REST guidelines also suggest that when in doubt it is advised to model 
things as resources.

Now back to the two proposed changes...

The "scan" operation returns "terms". One can model the set of terms as 
a resource addressed by the URL "/terms".

The search operation represents an algorithm that is modeled as 
aresource address by the URL "/search".

To summarize, the proposed changes make the HTTP binding for our 
interface more RESTful. IMHO, we should explicitly set a goal to make 
our HTTP binding be as RESTFul as possible.

BTW, as I said before, I am not a REST fundementalist (called 
RESTafarian). My history is more with SOAP/SOA than REST/ROA. However, I 
have begun to appreciate REST much more in recent times and feel that 
any HTTP binding done today MUST be as RESTFul as possible.

For a very good book on REST I suggest reading [RESTBOOK].

[RESTBOOK] Restfull Web Services, By Leonard Richardson, Sam Ruby, 2007
http://www.oreilly.com/catalog/9780596529260/

-- 
Regards,
Farrukh

Web: http://www.wellfleetsoftware.com