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

[Stefan Keller]

Hi,

This PDF and Website seem to be also very instructive explaining REST
basics (beyond fieldings PhD thesis).

I think, there can't be an authoritative reference what REST is -
since it's about web/IT architecture and SW engineering (and nobody
claims to the the only authority there).

There are epic discussions within SW engineering domain about REST and
SOAP. What's interesting for me as an observer, is that the REST
purists tend to think that HTML is enough and that there is no need
for a) JSON schema or b) aka "WSDL for REST". I personally think that
we need both two specs. (besides perhaps c) AtomPub) especially since
geospatial data is more structured and data oriented than hypertext.

Yours, Stefan


[1] http://www.restapitutorial.com/resources.html


2013/7/15 Peter Baumann <p.baumann at jacobs-university.de>:
> thanks, Allan, I have recorded the links no the OGC CoverageDWG pages for
> reference.
> IMHO this discussion underlines the ill-definedness of REST, but I guess we
> will have to live with it.
> Anyway, I got some more insights about REST from these threads, and I am
> grateful for all discussion.
>
> best,
> Peter
>
>
> On 07/13/2013 03:34 PM, Allan Doyle wrote:
>>
>> On Jul 13, 2013, at 3:13 AM, Peter Baumann
>> <p.baumann at jacobs-university.de>
>>   wrote:
>>
>>> Allan,
>>>
>>> thanks, that was very helpful indeed, in particular your elucidation on
>>> bounding boxes makes a lot of sense.
>>>
>>> So one conclusion from this thread IMHO is: just using KVP does not
>>> disqualify a service as RESTless.
>>> That allows us enough flexibility to come up with actionable, versatile,
>>> yet compact service definitions.
>>
>> I would not conclude, however, from "just using KVP does not disqualify a
>> service as RESTless" that you can start your REST design with KVP URLs. In
>> fact, I agree with Peter Rushforth that URLs that are heavily KVP are a
>> likely anti-pattern, or at least a big red flag.
>>
>>>> URLs themselves cannot be judged RESTful or not, certainly not in
>>>> isolation.
>>
>> ...
>>>>
>>>> Therefore KVP is actually not strictly not REST.
>>
>>
>>> I am surprised that after so many years there is still not an
>>> authoritative source. Obviously it is hard to define the concept. In a
>>> similar situation, when "NoSQL" came up in the database community, a general
>>> agreement emerged rather quickly, say, within a year or so.
>>
>> Some starting points:
>> http://en.wikipedia.org/wiki/Representational_state_transfer
>> http://tech.groups.yahoo.com/group/rest-discuss/messages/1?l=1 (the
>> earlier material here is probably more relevant, skim through it all quickly
>> to get an idea of the issues).
>>
>>         Allan
>>
>>> Hence, if we want to standardize REST services IMHO we should have a
>>> basis of adopted policies that guide us in our RESTful design. Guess I will
>>> suggest this to OGC.
>>>
>>> cheers,
>>> Peter
>>>
>>>
>>> AllanOn 07/13/2013 01:01 AM, Allan Doyle wrote:
>>>>
>>>> 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/featurecolle
>>
>>   cti
>>>>
>>>>   on/myhou
>>>>   se 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.
>>>>
>>>>         Allan
>>>>
>>>>
>>>> On Jul 12, 2013, at 5:48 PM, Peter Baumann
>>>> <p.baumann at jacobs-university.de>
>>>>   wrote:
>>>>
>>>>> 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
>>>>
>>>> _______________________________________________
>>>> 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
>
>
> --
> 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