Should we really call it REST?

[wilsaj]

It looks like there has been some discussion about a RESTful WaterOneFlow API: http://river.sdsc.edu/wiki/Default.aspx?Page=WaterOneFlow%20REST%20URL%20Structure

What we are calling REST in WOFpy is not the API in link above. Is this a problem?

It seems pedantic (and maybe it is), but REST has become a nebulous term and whatever we call "REST" in WOFpy is going to influence to some degree the meaning of REST in the context of WaterOneFlow.

[twhiteaker]

It's something CUAHSI-HIS was playing with but never formalized. I'll ask CUAHSI-HIS where they're going with that API.

[twhiteaker]

No feedback from HIS. The wiki page you found looks like it was updated in 2008. I found an email from the HIS developer from May, 2011, that shows slightly modified requests:
http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/values?location=USU:USU-LBR-Mendon&variable=USU:USU3&startDate=2005-08-01&endDate=2005-09-01

http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/series?site=USU:USU-LBR-Mendon

http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/variables?variable=USU:USU3

http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/variables?variable=

Note that there isn't the equivalent of GetSites.

[twhiteaker]

Another place describing the requests.
http://hydrocatalog.codeplex.com/wikipage?title=GenericOdWs%20Notes%20on%20Rest

[wilsaj]

My 2 cents:

I can see the value in the simplicity of allowing the SOAP request
parameters to be specified in a ?querystring. It's what we currently do in
WOFpy and it is pretty easy to do - it's just a different way of routing
requests. I think it's currently there mainly to make debugging easier
(which it does).

I don't think it should be called REST, though. One of the main ideas of
REST is giving each resource a unique URL. That's not possible with using
the same URL scheme as the WOF SOAP requests, because the nature of SOAP is
that URLs map to services where the nature of REST is that URLs map to
resources.

I like the ideas here the most:
http://river.sdsc.edu/wiki/WaterOneFlow%20REST%20URL%20Structure.ashx

Unique URLs work much better with the web's caching infrastructure, so I'm
in favor of putting required information to the left of the querystring.

The problem with URLs that look like this:
http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/values?location=USU:USU-LBR-Mendon&variable=USU:USU3&startDate=2005-08-01&endDate=2005-09-01

Is that the same thing could be found at:
http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/values?variable=USU:USU3&http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/values?location=USU:USU-LBR-Mendon&variable=USU:USU3&startDate=2005-08-01&endDate=2005-09-01
location=USU:USU-LBR-Mendonhttp://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/values?location=USU:USU-LBR-Mendon&variable=USU:USU3&startDate=2005-08-01&endDate=2005-09-01
&startDate=2005-08-01&endDate=2005-09-01http://hydro10.sdsc.edu/LBRSDSC/REST/waterml_1_0.svc/values?location=USU:USU-LBR-Mendon&variable=USU:USU3&startDate=2005-08-01&endDate=2005-09-01

But variable and location are the properties that make that set of values
unique. Start and end date is a little more subjective - using query string
for them might go either way since they are optional and in any case they
are less likely be requested so caching is less important.

Anyway, those are just my thoughts. I saw that there was going to be some
discussion on it today so I thought I'd throw some ideas down.

[twhiteaker]

On the HIS call today, the team agreed to go with "http://river.sdsc.edu/wiki/Default.aspx?Page=WaterOneFlow REST URL Structure".

[wilsaj]

Awesome.