[OSGeo-Standards] Was: "file" formats. Is: GeoWeb

Allan Doyle afdoyle at MIT.EDU
Fri Jul 12 16:01:09 PDT 2013

Here's my feeble attempt to describe the parts of REST that are being discussed.

URLs themselves cannot be judged RESTful or not, certainly not in isolation. Pure REST consists of the constraints elaborated earlier, and are pretty well described in Fielding's thesis.

One of the constraints is opaque URLs. That means that the URL itself should not be examined in terms of subcomponents. Thus http://example.com/dictionary/a/apple should not imply that you can also find http://example.com/dictionary/b/ball. In much the same way, you should not be able to take the existence of http://example.com/geometry?point&lat=42.0&lon=-72.0 to imply that you can also find http://example.com/geometry?point&lat=0&lon=0

That constraint rather naturally leads you to the idea of hypertext as the engine of application state, or HATEOAS. Since you can't assemble arbitrary URLs, they have to come from somewhere. They come from hypertext documents, and there has to be at least one origin from which you can discover (i.e. crawl to) the rest of them. By composing documents with specific links in them, you are essentially choosing which pathways a client can follow at any given point. That's basically the state of the hypertext system at that time. Given that the documents themselves are provided as representations of resources, and these representations are what travels from server to client, you have REpresentational State Transfer. A given resource can return different representations, so it can embed state into those representations in the form of URLs that may actually link back to the same resource. Thus if you have a resource that's a feature collection, both http://example.com/featurecollection/myhouse and http://example.com/featurecollection/yourhouse could actually be addressing the same resource (i.e. the feature collection) and be returning two different representations. Or they could be addressing two different resources at the feature level. You might never know.

But how does this help when you want to tell the feature collection resource to return a representation that's a map centered around a specific point, and that point can be expressed as a decimal latitude/longitude pair? You can't possibly return a list of enumerated allowable center points.

The REST community realized that you do need to have URLs that can be composed. They decided that the way to do this is via hypertext forms. Thus, you can have a form that has a latitude box and a longitude box. The web page itself is responsible for taking values entered into the form and constructing a URL with query parameters. Thus, to the client (generally the human using a browser), the URLs are really still opaque, but the hypertext brought enough info with it to the client side so that things can be composed from the form. 

Therefore KVP is actually not strictly not REST.

There's a lot that can be said about REST or not REST. Other than Fielding's thesis, I don't think there are any universally acclaimed definitive works on the topic. You can easily spend hours or days looking into it, and  it's something worth knowing more about if you want to have a well-rounded background in web technology. 

The thing to remember is that REST is a set of constraints specifically developed for hypermedia systems. Note that I'm pretty neutral and leaning towards pessimistic that REST is a sine qua non for building robust applications on the web. However, a good understanding of REST can be beneficial.


On Jul 12, 2013, at 5:48 PM, Peter Baumann <p.baumann at jacobs-university.de>

> Hi Stefan,
> like with other statements on what is RESTful and what not in this thread, I fail to find out what it's concretely.
> Still I am missing a commonly agreed, if not authoritative set of rules (not a PhD thesis!). I'd expect that, after these years of hot debates, the REST community has matured into a set of commonly agreed rules.
> Please let's not use KVP as a measure of RESTfulness, as long as stanzas like
>    ...?f=bmp
> are considered RESTful. And, BTW, any SQL query you need to send through KVP as the path syntax cannot represent it.
> So, one more time: where's the beef?
> thanks fo educating me,
> Peter
> On 07/12/2013 11:01 PM, Stefan Keller wrote:
>> Hi Carl
>> I apologize of sometimes being rude especially about OGC spec. I
>> accept OGC's role in standardization. To me this means high
>> responsibility and therefore I'm having high expectations about the
>> quality of the process and the output.
>> 2013/7/12 Carl Reed <creed at opengeospatial.org>:
>>> Interesting comment "WMTS is not RESTful yet because of other reasons".
>>> There is a presentation on the OGC website that documents Why WMTS is
>>> RESTful. This presentation was provided as part of the approval process for
>>> WMTS.
>> I did'nt find the presentation. Can you give me a link?
>> To backup my opinion that most OGC WxS aren't really fully RESTful I'd
>> like to point to the REST anti-patterns [1].
>> AFAIK most WxS including "WMTS using HTTP KVP encoding" (chap. 8) [2]
>> use anti-pattern 1 and 2 ("Tunneling everything through GET and
>> POST").
>> And WMTS is "overengineered" among others because it requires that "A
>> WMTS client SHOULD support both KVP and RESTful" (chap. 11.1).
>> Yours, Stefan
>> [1] http://www.infoq.com/articles/rest-anti-patterns
>> [2] http://www.opengeospatial.org/standards/wmts
>> http://www.infoq.com/articles/rest-anti-patterns
>> 2013/7/12 Carl Reed <creed at opengeospatial.org>:
>>> Stefan -
>>> Interesting comment "WMTS is not RESTful yet because of other reasons".
>>> There is a presentation on the OGC website that documents Why WMTS is
>>> RESTful. This presentation was provided as part of the approval process for
>>> WMTS.
>>> This inability to agree on what a RESTful service is (or the interface) has
>>> plagued REST work in the OGC for years. This is why the OGC Architecture
>>> Board suggests a pragmatic approach - implement REST interfaces for several
>>> existing OGC standards (WFS, WPS, WCS etc) and find out what in practice
>>> (not in the abstract) a RESTful OGC web service is and then document the
>>> best practice and guidance for future work.
>>> Also, GeoPackage defines rules for a container of geo-content (binary).
>>> These rules (requirements) define the internal format for storage on a
>>> device. The geometry elements are in line with OGC/ISO Simple Features and
>>> ISO 19107.
>>> Cheers
>>> Carl
>>> -----Original Message----- From: Stefan Keller
>>> Sent: Friday, July 12, 2013 3:27 AM
>>> To: Rushforth, Peter
>>> Cc: standards at lists.osgeo.org
>>> Subject: Re: [OSGeo-Standards] Was: "file" formats. Is: GeoWeb
>>> Hi Peter
>>> Thanks for the discussion. I think the book "REST in Practice" fits
>>> your thoughts and can be recommended for all as a basic lecture:
>>> http://restinpractice.com/book/
>>> As you say what's crucial to GeoWeb - and rather understimated in REST
>>> discussion until now - is the contract. That's why I like the above
>>> mentioned book. Producing a broadly accepted contract - accepted not
>>> only among us but even by browser manufacturers - makes it so
>>> difficult.
>>> You say there should be a contract against a server and a format, and
>>> a format and a client. That's interesting, But when separating the
>>> server-client-contract don't you loose something like state change
>>> protocol metadata (and negotiation) which you also have in a contract?
>>> To me that's where "WSDL for REST" comes in.
>>> Web map raster tiles already come close to a format since its JPG, PNG
>>> etc. (and WMTS is not RESTful yet because of other reasons). Perhaps
>>> the grouping information could go into the protocol metadata? For
>>> raster to me there's no need for links - except the spatial
>>> relationship which already is powerful.
>>> For vector features and feature collections we already have xlink and
>>> grouping - to there's nothing to do here for a contract I think. To me
>>> the elephant in the room is which format: Interestingly neither
>>> GeoJSON nor GeoPackage have been mentioned yet!?
>>> Yours, Stefan
>>> 2013/7/11 Rushforth, Peter <Peter.Rushforth at nrcan-rncan.gc.ca>:
>>>> Arnulf,
>>>>> Which is why the underlying architecture paradigm is called resource
>>>>> orientation.
>>>> Resource and representation is part of REST, yes.  Let's try to be a bit
>>>> clear about terminology.  At least REST has a definition.
>>>>> If we take some raster data to be the resource
>>>> I would say that's not a great starting point for a resource data model.
>>>> Maybe "the earth", or some part thereof would be a more concrete concept?
>>>>> then any part and information derived from this data is a representation
>>>>> of this resource.
>>>> Yes, that's one aspect of the resource-representation duality: the server
>>>> is free to serve up a partial representation of the whole resource, not only
>>>> different formats, languages etc. The partial nature of the representation
>>>> is mitigated by the ability to include links to other parts in hypertext.
>>>>> It is perfectly fine for a representation (for example a file) to not
>>>>> have any hypertext component or link embedded in them (think PNG image).
>>>>> It can still be part of a REST environment. The raster representation
>>>>> that is returned for a GET request could well be wrapped into some
>>>>> hypertext, this would make things even nicer but is not required at all
>>>>> times.
>>>> I'm not sure what you mean by "at all times".  That statement is taken by
>>>> most
>>>> "REST APIs" to mean "never", or "only incidentally, but not required by
>>>> this spec"
>>>> from what I've seen.
>>>> We should be starting the other way around, IMHO where we're defining the
>>>> hypermedia
>>>> context for services, and let implementers work out their own rules for
>>>> the URI
>>>> for this image or that coverage.  Note that hypermedia can be quite
>>>> sophisticated,
>>>> with standards-based URI Templates [1]
>>>> Cheers,
>>>> Peter
>>>> [1] http://tools.ietf.org/html/rfc6570
>>>> _______________________________________________
>>>> Standards mailing list
>>>> Standards at lists.osgeo.org
>>>> http://lists.osgeo.org/mailman/listinfo/standards
>>> _______________________________________________
>>> Standards mailing list
>>> Standards at lists.osgeo.org
>>> http://lists.osgeo.org/mailman/listinfo/standards
>> _______________________________________________
>> Standards mailing list
>> Standards at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/standards
> -- 
> Dr. Peter Baumann
> - Professor of Computer Science, Jacobs University Bremen
>   www.faculty.jacobs-university.de/pbaumann
>   mail: p.baumann at jacobs-university.de
>   tel: +49-421-200-3178, fax: +49-421-200-493178
> - Executive Director, rasdaman GmbH Bremen (HRB 26793)
>   www.rasdaman.com, mail: baumann at rasdaman.com
>   tel: 0800-rasdaman, fax: 0800-rasdafax, mobile: +49-173-5837882
> "Si forte in alienas manus oberraverit hec peregrina epistola incertis ventis dimissa, sed Deo commendata, precamur ut ei reddatur cui soli destinata, nec preripiat quisquam non sibi parata." (mail disclaimer, AD 1083)
> _______________________________________________
> Standards mailing list
> Standards at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/standards

More information about the Standards mailing list