But it may not actually be a RESTful service since they don't seem to
have a way to reach all their entries via some kind of index. I could
wrap it in a RESTful service, though.
Wikipedia on the other hand is more RESTful. It has an actual entry
point and everything in it can be reached by traversing hypertext
documents.
> and in some cases, we might even be able to force it using a slug (Not
> that I like that)
> Pat.
> On Mar 20, 2009, at 1:37 PM, Allan Doyle wrote:
>> On Mar 20, 1:05 pm, Pat G Cappelaere <cappela...@gmail.com> wrote:
>>> Allan,
>>> Are you saying that if you were to create a new resource by posting
>>> against its collection like:
>>> POST /sps/tasks ...<entry ... />
>>> and the service returns the new resource id in the header as: /sps/
>>> tasks/23
>>> This would not be in the spirit of REST or RFC3986?
>> No. That would be quite the opposite of what I'm saying. If you did
>> not get the new resource ID, you'd have to intuit it. That would be
>> silly.
>> But I would also not have any reason to complain if I POST to your
>> URI
>> and get back /sps/archive/foo/bar/baz/23 It's your service, you make
>> up the URI. I live with it.
>> Allan
>>> Pat.
>>>> Apparently my message has caused confusion. I'm not commenting
>>>> specifically on the OGC RFC, I'm commenting more on the fact that
>>>> templating the path component doesn't seem to be in the spirit of
>>>> REST
>>>> or of RFC3986. The path is meant to be opaque. That means that no
>>>> special meaning should be derived from it, no matter how nicely it
>>>> decomposes into elements you might modify.
> With tiles, and without templating, opaque URLs are, if not tricky, at
> least a performance issue. A simple implementation of a fully RESTy
> tile service would look much like KML regions. The XML form of each
> tile resource would provide links to the neighboring resources, the
> child resources, the parent resources and the current image
> representation.
Nobody says REST is higher performance. It's more robust and
evolvable, but to get the benefits you have to get away from RPC.
Consider HTML: browsers don't use RPC protocols to get the media
associated with a web page, they act on linked URIs. We have to do the
same thing to get the same properties in a GIS system. It may turn out
that REST isn't a good fit for this kind of application, or that loose
coupling has more overhead than one wants to deal with.
As it stands, the WMTS "RESTful encoding" is just as much RPC as the
old KVP protocol. We're still asked to call a
Get(Tile)ResourceRepresentation method on the service, but this time
with a URI instead of a query string. There's no actual resource
architecture in there yet, and I think the unification of KVP, SOAP,
and REST will have to yield before there can be one. The effort to
have harmony, to have KVP, SOAP, and REST flavors of a single
architecture baffles me.
> 100% self-describing, but expensive to traverse, since getting any
> image tile requires also getting the descriptive resource document.
> ACK! ACK!
> P.
There's caching, of course, but that might be part of the overhead you
don't want to pay.
And then there's "code on demand" [2]. If you've used OpenLayers,
you've been taking advantage of this aspect of the web. An OpenLayers- type module could loosen coupling between RESTful clients and servers
by fetching the current rules for mapping geographic region/scale to
tile URIs (URI templates and algorithms) from the server instead of
baking them in. It seems to me that code on demand is going to be
useful for non-browser clients as well.
>>>> Among other things, a RESTful tile service must give clients a
>>>> bookmarkable entry point from which it can find tile resources. The
>>>> "RESTful" WMTS does not. The service metadata document only
>>>> provides
>>>> the base URL. Clients can not follow their noses from there. The
>>>> proposed WMTS is not RESTful.
>>>> Furthermore, GetResourceRepresentation (especially sections
>>>> 10.2.1 and
>>>> 10.3.2) isn't a RESTful protocol as much as it is hierarchical URL
>>>> fetishism. Let's accept (for now) the essential parameters as
>>>> they are:
>>>> in that exact order, has no demonstrable benefit unless the
>>>> resource
>>>> at (for example)
>>>> {WMTSBaseURL}/{layer}
>>>> always contains links to the contained styles. Strict hypertext as
>>>> engine of application state, in other words. Since there's no
>>>> sign of
>>>> the hypertext constraint in the spec, I see no reason why a URL
>>>> like
>>>> or any other ordering of the parameters in a query string,
>>>> shouldn't
>>>> be equally valid.
>>>> This proposed WMTS spec cries out for URI templating, the kind of
>>>> hypertext used in the OpenSocial API [1]. The one bookmarkable
>>>> entry
>>>> point for the service would be an XML document that provides URI
>>>> templates to a client, using forms 1 or 2 (shown above). This
>>>> way, you
>>>> can avoid baking a particular server implementation into clients
>>>> unnecessarily [2].
>>> I'm jumping in here because I have a lot to learn about this stuff.
>>> What better way to learn than to be bloodied at the hands of a crowd
>>> that has had more time to think about it than me. Be gentle is all I
>>> ask...
>>> I'm not sure I like where [2] leads. It seems to me that the path
>>> portions of a URI should remain opaque and should not be
>>> templated. If
>>> you're going to allow the client to construct a URI then the
>>> construction ought to go into the query part of the URI [3].
>>> In this instance, the bit with the widest variability would be the
>>> {style}, so why not push that to the query part. The other parts are
>>> finite and ought to be bounded by the spec. Let's say there was a
>>> tile
>>> series with only one style. I could see a series of hypertext
>>> documents containing something like:
>>> But once you're viewing maps in a given style, you're more likely to
>>> keep looking at that style. So you'd only need the style at the
>>> "entry
>>> point" into a set of maps (more about this below), after that the
>>> map
>>> tiling engine can provide perfectly fine opaque URLs
>>> But if we back up and decide to walk the REST walk, and say that the
>>> the hypertext document is all we need, then there's nothing that
>>> says
>>> that the URI have to be composable at all.
>>> The tiling engine is the only thing that needs to know the
>>> relationship between a tile and a URI.
>>> We run into trouble when we want to layer tiles from two different
>>> engines. In that case we expect (or have been programmed to think we
>>> should expect) to be able to feed the same URL components into two
>>> different engines to get two tiles that can be layered. But maybe
>>> what
>>> we need are some other helper URI:
>>> If that returned a nice bbox (maybe a GeoJSON bbox), then we can
>>> take
>>> the bbox and hand it to a different tiling engine to get back the
>>> corresponding tile:
>>> Now getting back to the "entry point". So what if you have a tiling
>>> engine that can show a zillion different styles? Wouldn't you want
>>> to
>>> list them all somewhere so that people can find them and choose
>>> which
>>> ones they want? Wouldn't you want them to show up in Google? Of
>>> course. So you make an index page and list them. Or make a series of
>>> index pages and link them together. Or better yet, use AtomPub to
>>> provide access to the full set.
>>> And finally, the tiling spec can stop talking about the
>>> composition of
>>> the URI and can start talking about the semantics of what goes into
>>> the "rel" attribute [5]
>> Apparently my message has caused confusion. I'm not commenting
>> specifically on the OGC RFC, I'm commenting more on the fact that
>> templating the path component doesn't seem to be in the spirit of
>> REST
>> or of RFC3986. The path is meant to be opaque. That means that no
>> special meaning should be derived from it, no matter how nicely it
>> decomposes into elements you might modify.
[mailto:geo-web-rest@googlegroups.com] On Behalf Of Sean Gillies
Sent: March 23, 2009 9:03 AM
To: geo-web-rest@googlegroups.com
Subject: [Geo-Web-REST] Re: Proposed OGC REST considered harmful
On Mar 20, 2009, at 11:02 AM, Paul Ramsey wrote:
> With tiles, and without templating, opaque URLs are, if not tricky, at
> least a performance issue. A simple implementation of a fully RESTy
> tile service would look much like KML regions. The XML form of each
> tile resource would provide links to the neighboring resources, the
> child resources, the parent resources and the current image
> representation.
Nobody says REST is higher performance. It's more robust and
evolvable, but to get the benefits you have to get away from RPC.
Consider HTML: browsers don't use RPC protocols to get the media
associated with a web page, they act on linked URIs. We have to do the
same thing to get the same properties in a GIS system. It may turn out
that REST isn't a good fit for this kind of application, or that loose
coupling has more overhead than one wants to deal with.
As it stands, the WMTS "RESTful encoding" is just as much RPC as the
old KVP protocol. We're still asked to call a
Get(Tile)ResourceRepresentation method on the service, but this time
with a URI instead of a query string. There's no actual resource
architecture in there yet, and I think the unification of KVP, SOAP,
and REST will have to yield before there can be one. The effort to
have harmony, to have KVP, SOAP, and REST flavors of a single
architecture baffles me.
> 100% self-describing, but expensive to traverse, since getting any
> image tile requires also getting the descriptive resource document.
> ACK! ACK!
> P.
There's caching, of course, but that might be part of the overhead you
don't want to pay.
And then there's "code on demand" [2]. If you've used OpenLayers,
you've been taking advantage of this aspect of the web. An OpenLayers- type module could loosen coupling between RESTful clients and servers
by fetching the current rules for mapping geographic region/scale to
tile URIs (URI templates and algorithms) from the server instead of
baking them in. It seems to me that code on demand is going to be
useful for non-browser clients as well.
>>>> Among other things, a RESTful tile service must give clients a
>>>> bookmarkable entry point from which it can find tile resources. The
>>>> "RESTful" WMTS does not. The service metadata document only
>>>> provides
>>>> the base URL. Clients can not follow their noses from there. The
>>>> proposed WMTS is not RESTful.
>>>> Furthermore, GetResourceRepresentation (especially sections
>>>> 10.2.1 and
>>>> 10.3.2) isn't a RESTful protocol as much as it is hierarchical URL
>>>> fetishism. Let's accept (for now) the essential parameters as
>>>> they are:
>>>> in that exact order, has no demonstrable benefit unless the
>>>> resource
>>>> at (for example)
>>>> {WMTSBaseURL}/{layer}
>>>> always contains links to the contained styles. Strict hypertext as
>>>> engine of application state, in other words. Since there's no
>>>> sign of
>>>> the hypertext constraint in the spec, I see no reason why a URL
>>>> like
>>>> or any other ordering of the parameters in a query string,
>>>> shouldn't
>>>> be equally valid.
>>>> This proposed WMTS spec cries out for URI templating, the kind of
>>>> hypertext used in the OpenSocial API [1]. The one bookmarkable
>>>> entry
>>>> point for the service would be an XML document that provides URI
>>>> templates to a client, using forms 1 or 2 (shown above). This
>>>> way, you
>>>> can avoid baking a particular server implementation into clients
>>>> unnecessarily [2].
>>> I'm jumping in here because I have a lot to learn about this stuff.
>>> What better way to learn than to be bloodied at the hands of a crowd
>>> that has had more time to think about it than me. Be gentle is all I
>>> ask...
>>> I'm not sure I like where [2] leads. It seems to me that the path
>>> portions of a URI should remain opaque and should not be
>>> templated. If
>>> you're going to allow the client to construct a URI then the
>>> construction ought to go into the query part of the URI [3].
>>> In this instance, the bit with the widest variability would be the
>>> {style}, so why not push that to the query part. The other parts are
>>> finite and ought to be bounded by the spec. Let's say there was a
>>> tile
>>> series with only one style. I could see a series of hypertext
>>> documents containing something like:
>>> But once you're viewing maps in a given style, you're more likely to
>>> keep looking at that style. So you'd only need the style at the
>>> "entry
>>> point" into a set of maps (more about this below), after that the
>>> map
>>> tiling engine can provide perfectly fine opaque URLs
>>> But if we back up and decide to walk the REST walk, and say that the
>>> the hypertext document is all we need, then there's nothing that
>>> says
>>> that the URI have to be composable at all.
>>> The tiling engine is the only thing that needs to know the
>>> relationship between a tile and a URI.
>>> We run into trouble when we want to layer tiles from two different
>>> engines. In that case we expect (or have been programmed to think we
>>> should expect) to be able to feed the same URL components into two
>>> different engines to get two tiles that can be layered. But maybe
>>> what
>>> we need are some other helper URI:
>>> If that returned a nice bbox (maybe a GeoJSON bbox), then we can
>>> take
>>> the bbox and hand it to a different tiling engine to get back the
>>> corresponding tile:
>>> Now getting back to the "entry point". So what if you have a tiling
>>> engine that can show a zillion different styles? Wouldn't you want
>>> to
>>> list them all somewhere so that people can find them and choose
>>> which
>>> ones they want? Wouldn't you want them to show up in Google? Of
>>> course. So you make an index page and list them. Or make a series of
>>> index pages and link them together. Or better yet, use AtomPub to
>>> provide access to the full set.
>>> And finally, the tiling spec can stop talking about the
>>> composition of
>>> the URI and can start talking about the semantics of what goes into
>>> the "rel" attribute [5]
As a co-author of the WMTS draft specification, I'd like to pipe in
here
with some of my own views and justifications of the proposed "RESTful"
interface of the specification.
First and foremost, the proposed WMTS RESTful interface is in
some aspects a necessary compromise. OGC service implementation
specifications are bound by many requirements (including, but not
limited
to, the dictates of the OGC Common Implementation specification, OGC
document 06-121r3). OGC service implementation specifications have
always been defined, right from the core, with a service-oriented
architecture, and there are many requirements in place that anchor
specifications to this type of architecture. That's not to say that
OGC
specifications can't evolve into a more resource-oriented approach,
but this evolution will take some time. There are many existing
interoperable OGC specifications to consider.
So, as a result of the existing framework of OGC specifications and
requirements, the WMTS specification was defined in the same manner
as the other existing OGC service implementation specifications.
It's defined in terms of a set of service-oriented operations
(GetCapabilities, GetTile, GetFeatureInfo), which can be invoked
either
through HTTP GET using a key-value-pair encoding of the operation
parameters, or through HTTP POST using an XML encoding of the
operation
parameters. This is currently an essential aspect of an OGC service
implementation specification.
But of course it's clear that there's a growing trend for HTTP
services
to return to the grass roots of the HTTP protocol and do things in
a more resource-oriented and RESTful way. And a tiling service is
a prime candidate for a service that could be, and indeed should be,
designed in this way.
And here, of course, comes the compromise. The resulting draft
specification does what it can to introduce a RESTful interface while
also maintaining the underlying service-oriented design of the
service.
In my opinion, the RESTful interface that has been defined does a
decent
job of satisfying much of what it means to be RESTful.
Let me address some of the specific critiques.
Sean Gillies wrote:
> Requiring all tiles to be at URLs like
> in that exact order, has no demonstrable benefit unless the resource at
> (for example)
> {WMTSBaseURL}/{layer}
> always contains links to the contained styles.
That's not true at all. There are many demonstrable benefits of
defining
canonical URLs like this.
a) It allows a WMTS to be implemented as nothing more than a web
server
on top of a file system. This not only allows for lightning-fast
WMTS servers that can be implemented with zero lines of code, but
it
also allows, for free, a WMTS to take full advantage of the
various
RESTful HTTP communication optimizations that web servers offer
(such as the "Last-Modified"/"If-Modified-Since" headers, etc.).
b) It allows for really simple resource caching mechanisms that have
absolutely no knowledge of the structure of the resource URLs,
since every tile has exactly one canonical URL (with the possible
exception of base-URL aliases, of course).
c) Unlike with the traditional KVP and XML/SOAP operation encodings,
where the URL+body represents an operation, the RESTful encoding
of a tile request is really the address of the tile resource,
with the operation (GET) being specified at the HTTP level.
The RESTful encoding of a tile request consists of all nouns, and
the HTTP operation indicates what operation is being performed on
the addressed resource. E.g., the URL of a tile resource is:
And the specification states that to retrieve this tile, the
client
should send an HTTP GET request to this URL. Currently GET is
the
only HTTP operation defined for the RESTful interface, but it's
clear that if we were to extend the interface to allow a WMTS
client
to create or update the tile resource indicated by the above URL,
this would be achieved by sending an HTTP PUT request to this URL
(i.e., the same URL that's used in a GET request to retrieve the
tile), and that if a client were to have the ability to delete a
tile, it would send an HTTP DELETE request to this same URL.
Point c) is really the essence of what it means to be RESTful.
Where the WMTS specification compromises is in how these capabilities
are reported to the client. The current draft WMTS specification
takes advantage of the fact that only the GET operation is defined for
RESTful access, and that the service-oriented operations also happen
to be read-only operations. This allows the specification and the
service's capabilities document to align the two so that the bulk
of the specification and the service's capabilities document can be
used to describe both the service-oriented and the RESTful interfaces.
The alternative would be to describe the service-oriented interface
and
the RESTful interface in completely different terms, resulting in what
what would in essence be two completely different specifications.
The resulting specification is, I admit, a bit of a patchwork when it
comes to introducing a RESTful interface. It conflates and (in some
ways intentionally) confuses the fundamentally-different paradigms of
service-oriented and resource-oriented architectures. But in the end,
I maintain that the so-called RESTful interface of the WMTS really is
RESTful in the important and practical senses of the term. I think
the only way that REST fundamentalists would be truly happy with the
specification is if the service-oriented aspects of the specification
were stripped out entirely. But that simply isn't an option for an
OGC service implementation specification, at least not in the current
climate.
Sean Gillies also wrote:
> Among other things, a RESTful tile service must give clients a
> bookmarkable entry point from which it can find tile resources. The
> "RESTful" WMTS does not. The service metadata document only provides
> the base URL. Clients can not follow their noses from there. The
> proposed WMTS is not RESTful.
The fact that "clients can not follow their noses" does not make a
service not RESTful. "Connectedness" (the term used by Richardson &
Ruby) may be a desired trait for RESTful web services to have, but it
certainly isn't a required one. And in the case of a WMTS service,
there's a certain aspect of practicality that must be considered.
It may be feasible to introduce a few higher-order resource documents
that reference its sub-resources in a connected way (such as a layer
document referencing styles-of-layer documents, etc.), but we'd have
to
be careful not to introduce too many levels of indirection. A primary
goal of the WMTS specification is efficiency, and so we wouldn't want
the client to have to hop through a dozen documents just to get to the
first tile. And in the end, since the tile resources are organized in
a matrix, at the very least the client application would have to be
responsible for assembling the TileRow and TileCol components of the
URL itself. We certainly wouldn't want to introduce multi-megabyte
documents containing explicit references to each and every tile of
each
and every row of each and every tile matrix. So clients wouldn't be
able to "follow their noses" all the way to the tile resources
anyways.
Perhaps something like the KML approach is a way around that.
But again, a primary goal of the WMTS specification is efficiency,
and the currently-specified approach was selected because it can be
implemented very efficiently (more efficiently than a KML client).
A client application needs only to read a single reasonably-sized
capabilities document, and it has all the information it needs to
directly fetch every single tile the service has to offer without
having
to muck about with intermediate XML documents.
Sean Gillies also wrote:
> There's no actual resource architecture in there yet, and I think the
> unification of KVP, SOAP, and REST will have to yield before there can
> be one. The effort to have harmony, to have KVP, SOAP, and REST flavors
> of a single architecture baffles me.
Yes, even though I'm a co-author of the WMTS specification, I agree
with
you here. This version of the WMTS specification was bound by current
OGC policies, practices and interests to attempt such harmony, but in
the
long run, future version of the WMTS are probably going to have to
choose
one way or the other in order to cleanly represent a single
architecture.
Part of the goal of introducing a RESTful interface to the WMTS
service
is to plunge the community into these issues and get a feel for how
RESTful OGC services in general should evolve. Thus, discussions like
this are not only inevitable, but desired. What the next version of
the WMTS specification will look like will be determined in part by
the outcome of community discussions like this.
In the meantime, though, I maintain that the RESTful interface of
the WMTS as currently defined really is RESTful in the important and
practical senses of the term, and, despite the shortcomings in the way
it's defined, can still be used in a RESTful way and reap the benefits
that RESTful web services have to offer.
---
Keith Pomakis <poma...@cubewerx.com>
Senior Software Developer, CubeWerx Inc.
15 rue Gamelin, Gatineau, Québec J8Y 3B5
Phone: 819-771-8303 x202, FAX: 819-771-8388
> > in that exact order, has no demonstrable benefit unless the resource at
> > (for example)
> > {WMTSBaseURL}/{layer}
> > always contains links to the contained styles.
> That's not true at all. There are many demonstrable benefits of
> defining
> canonical URLs like this.
> a) It allows a WMTS to be implemented as nothing more than a web
> server
> on top of a file system. This not only allows for lightning-fast
> WMTS servers that can be implemented with zero lines of code, but
> it
> also allows, for free, a WMTS to take full advantage of the
> various
> RESTful HTTP communication optimizations that web servers offer
> (such as the "Last-Modified"/"If-Modified-Since" headers, etc.).
A URI-template driven service could also be implemented on a
filesystem. The client would have to compute the URI value in order
to retrieve the tile which should not impede a fast response by the
server, as a template-derived URL would look much the same as a hard-
coded URL.
Roy Fielding has this to say:
"A REST API must not define fixed resource names or hierarchies (an
obvious coupling of client and server). Servers must have the freedom
to control their own namespace. Instead, allow servers to instruct
clients on how to construct appropriate URIs, such as is done in HTML
forms and URI templates, by defining those instructions within media
types and link relations. [Failure here implies that clients are
assuming a resource structure due to out-of band information, such as
a domain-specific standard, which is the data-oriented equivalent to
RPC's functional coupling]."
> b) It allows for really simple resource caching mechanisms that have
> absolutely no knowledge of the structure of the resource URLs,
> since every tile has exactly one canonical URL (with the possible
> exception of base-URL aliases, of course).
I'm not sure how a templating mechanism would prevent similar caching?
Keith Pomakis also wrote:
> Sean Gillies also wrote:
> > Among other things, a RESTful tile service must give clients a
> > bookmarkable entry point from which it can find tile resources. The
> > "RESTful" WMTS does not. The service metadata document only provides
> > the base URL. Clients can not follow their noses from there. The
> > proposed WMTS is not RESTful.
> The fact that "clients can not follow their noses" does not make a
> service not RESTful. "Connectedness" (the term used by Richardson &
> Ruby) may be a desired trait for RESTful web services to have, but it
> certainly isn't a required one. And in the case of a WMTS service,
> there's a certain aspect of practicality that must be considered.
> It may be feasible to introduce a few higher-order resource documents
> that reference its sub-resources in a connected way (such as a layer
> document referencing styles-of-layer documents, etc.), but we'd have
> to
> be careful not to introduce too many levels of indirection. A primary
> goal of the WMTS specification is efficiency, and so we wouldn't want
> the client to have to hop through a dozen documents just to get to the
> first tile. And in the end, since the tile resources are organized in
> a matrix, at the very least the client application would have to be
> responsible for assembling the TileRow and TileCol components of the
> URL itself. We certainly wouldn't want to introduce multi-megabyte
> documents containing explicit references to each and every tile of
> each
> and every row of each and every tile matrix. So clients wouldn't be
> able to "follow their noses" all the way to the tile resources
> anyways.
> Perhaps something like the KML approach is a way around that.
> But again, a primary goal of the WMTS specification is efficiency,
> and the currently-specified approach was selected because it can be
> implemented very efficiently (more efficiently than a KML client).
> A client application needs only to read a single reasonably-sized
> capabilities document, and it has all the information it needs to
> directly fetch every single tile the service has to offer without
> having
> to muck about with intermediate XML documents.
Would adding the additional possibility of different representations
of the resources as per Paul's suggestion be useful? The approach
taken to canonicalize the urls in order that clients can generate them
would seem to be competing with the URI-templates idea. You don't
*have* to muck about with the other representations of the resource,
but perhaps they would have some other benefit, for discovery
perhaps.
> Part of the goal of introducing a RESTful interface to the WMTS
> service
> is to plunge the community into these issues and get a feel for how
> RESTful OGC services in general should evolve. Thus, discussions like
> this are not only inevitable, but desired. What the next version of
> the WMTS specification will look like will be determined in part by
> the outcome of community discussions like this.
This discussion is great, and it's how I'm learning the subject.
> As a co-author of the WMTS draft specification, I'd like to pipe in
> here
> with some of my own views and justifications of the proposed "RESTful"
> interface of the specification.
> First and foremost, the proposed WMTS RESTful interface is in
> some aspects a necessary compromise. OGC service implementation
> specifications are bound by many requirements (including, but not
> limited
> to, the dictates of the OGC Common Implementation specification, OGC
> document 06-121r3). OGC service implementation specifications have
> always been defined, right from the core, with a service-oriented
> architecture, and there are many requirements in place that anchor
> specifications to this type of architecture. That's not to say that
> OGC
> specifications can't evolve into a more resource-oriented approach,
> but this evolution will take some time. There are many existing
> interoperable OGC specifications to consider.
> So, as a result of the existing framework of OGC specifications and
> requirements, the WMTS specification was defined in the same manner
> as the other existing OGC service implementation specifications.
> It's defined in terms of a set of service-oriented operations
> (GetCapabilities, GetTile, GetFeatureInfo), which can be invoked
> either
> through HTTP GET using a key-value-pair encoding of the operation
> parameters, or through HTTP POST using an XML encoding of the
> operation
> parameters. This is currently an essential aspect of an OGC service
> implementation specification.
> But of course it's clear that there's a growing trend for HTTP
> services
> to return to the grass roots of the HTTP protocol and do things in
> a more resource-oriented and RESTful way. And a tiling service is
> a prime candidate for a service that could be, and indeed should be,
> designed in this way.
> And here, of course, comes the compromise. The resulting draft
> specification does what it can to introduce a RESTful interface while
> also maintaining the underlying service-oriented design of the
> service.
> In my opinion, the RESTful interface that has been defined does a
> decent
> job of satisfying much of what it means to be RESTful.
Keith,
We'll simply have to agree to disagree about the necessity of this
compromise. The result of it is an architecture that remains more RPC
than REST in the way that it will be used. I'm concerned that once
this spec is approved and the marketing people starting trumpeting the
"REST API", misunderstanding of REST will become entrenched in the
geospatial community.
You've made a lot of good points below, and I'd like to discuss them
further ...
>> in that exact order, has no demonstrable benefit unless the
>> resource at
>> (for example)
>> {WMTSBaseURL}/{layer}
>> always contains links to the contained styles.
> That's not true at all. There are many demonstrable benefits of
> defining
> canonical URLs like this.
> a) It allows a WMTS to be implemented as nothing more than a web
> server
> on top of a file system. This not only allows for lightning-fast
> WMTS servers that can be implemented with zero lines of code, but
> it
> also allows, for free, a WMTS to take full advantage of the
> various
> RESTful HTTP communication optimizations that web servers offer
> (such as the "Last-Modified"/"If-Modified-Since" headers, etc.).
> b) It allows for really simple resource caching mechanisms that have
> absolutely no knowledge of the structure of the resource URLs,
> since every tile has exactly one canonical URL (with the possible
> exception of base-URL aliases, of course).
You are absolutely right about the benefits of canonical URIs, but the
argument for simplicity of tile deployment and hosting has nothing to
do with REST.
> c) Unlike with the traditional KVP and XML/SOAP operation encodings,
> where the URL+body represents an operation, the RESTful encoding
> of a tile request is really the address of the tile resource,
> with the operation (GET) being specified at the HTTP level.
> The RESTful encoding of a tile request consists of all nouns, and
> the HTTP operation indicates what operation is being performed on
> the addressed resource. E.g., the URL of a tile resource is:
> And the specification states that to retrieve this tile, the
> client
> should send an HTTP GET request to this URL. Currently GET is
> the
> only HTTP operation defined for the RESTful interface, but it's
> clear that if we were to extend the interface to allow a WMTS
> client
> to create or update the tile resource indicated by the above URL,
> this would be achieved by sending an HTTP PUT request to this URL
> (i.e., the same URL that's used in a GET request to retrieve the
> tile), and that if a client were to have the ability to delete a
> tile, it would send an HTTP DELETE request to this same URL.
> Point c) is really the essence of what it means to be RESTful.
I do like the concept of dereferenceable tile resources identified by
URIs. It's the best part of the spec. It's more accurate to say this
is the essence of web architecture.
> Where the WMTS specification compromises is in how these capabilities
> are reported to the client. The current draft WMTS specification
> takes advantage of the fact that only the GET operation is defined for
> RESTful access, and that the service-oriented operations also happen
> to be read-only operations. This allows the specification and the
> service's capabilities document to align the two so that the bulk
> of the specification and the service's capabilities document can be
> used to describe both the service-oriented and the RESTful interfaces.
> The alternative would be to describe the service-oriented interface
> and
> the RESTful interface in completely different terms, resulting in what
> what would in essence be two completely different specifications.
> The resulting specification is, I admit, a bit of a patchwork when it
> comes to introducing a RESTful interface. It conflates and (in some
> ways intentionally) confuses the fundamentally-different paradigms of
> service-oriented and resource-oriented architectures. But in the end,
> I maintain that the so-called RESTful interface of the WMTS really is
> RESTful in the important and practical senses of the term. I think
> the only way that REST fundamentalists would be truly happy with the
> specification is if the service-oriented aspects of the specification
> were stripped out entirely. But that simply isn't an option for an
> OGC service implementation specification, at least not in the current
> climate.
More important than how capabilities are reported to the client (after
all, with REST we have a uniform interface) is how the tile resource
URIs are exposed to the client.
The spec says:
10.2.1 GetResourceRepresentation request
The ServiceMetadata document in the resource oriented architecture
style should contain
a description of a resource with the name "Tile". The “Get” element of
the
GetResourceRepresentation operation shall have a xlink:href attribute
that advertises the
canonical URL to retrieve tiles.
A URL referencing a tile map image must have the following syntax:
{WMTSBaseURL}/{layer}/{style}/{firstDimension}/{...}/ {lastDimension}/{TileMatrix
Set}/{TileMatrix}/{TileRow}/{TileCol}.{format_extension}
Even though the tiles may be web resources, the rules a client must
follow to find them are entirely out of band. To get at them, we have
to interact with the service in RPC style, effectively calling the
service's GetResourceRepresentation method.
Also: examples of canonical tile URIs advertised in service metadata
seem to be absent from the spec, or am I just overlooking them?
> Sean Gillies also wrote:
>> Among other things, a RESTful tile service must give clients a
>> bookmarkable entry point from which it can find tile resources. The
>> "RESTful" WMTS does not. The service metadata document only provides
>> the base URL. Clients can not follow their noses from there. The
>> proposed WMTS is not RESTful.
> The fact that "clients can not follow their noses" does not make a
> service not RESTful. "Connectedness" (the term used by Richardson &
> Ruby) may be a desired trait for RESTful web services to have, but it
> certainly isn't a required one. And in the case of a WMTS service,
> there's a certain aspect of practicality that must be considered.
> It may be feasible to introduce a few higher-order resource documents
> that reference its sub-resources in a connected way (such as a layer
> document referencing styles-of-layer documents, etc.), but we'd have
> to
> be careful not to introduce too many levels of indirection. A primary
> goal of the WMTS specification is efficiency, and so we wouldn't want
> the client to have to hop through a dozen documents just to get to the
> first tile. And in the end, since the tile resources are organized in
> a matrix, at the very least the client application would have to be
> responsible for assembling the TileRow and TileCol components of the
> URL itself. We certainly wouldn't want to introduce multi-megabyte
> documents containing explicit
>Also: examples of canonical tile URIs advertised in service metadata >seem to be absent from the spec, or am I just overlooking them?
This was also analyzed by the WMS group and we concluded that it was redundant with the spec itself that already tells you the way canonical URL has to be represented. It was finally removed but could be put back if needed.
>How is "connectedness" not required? Fielding says it's part of the >essence of REST.
Connectedness was also analyzed but nobody seemed interested in a collection of XML files that you have to explore to discover a tiles at the end.
What is the real point on discovering tiles?
In my opinion, tile systems that uses power of 2 related scales to produce tiles can take advantage of this. You can build a client that shows you the whole world and the you can zoom in following the dependencies of the corse tiles to the next detailed levels an so on. That is exactly what google earth does with "superoverlays" [1].
But the important questions is, why we have to explore the tiles this way? Why simply can I start form a low scale denominator and zoom out to a lower resolution? Then the superresolution connectness of the tiles is useless. And let me remain you that WMTS tiles has not to follow the power of 2 relation.
That is the real advantage of discovering tiles? To index them in google search?, There could be millions of them!. They are not searchable. They are binary sequences to the computer.
> Sean Gillies said >> Also: examples of canonical tile URIs advertised in service metadata >> seem to be absent from the spec, or am I just overlooking them? > This was also analyzed by the WMS group and we concluded that it > was redundant with the spec itself that already tells you the way > canonical > URL has to be represented. It was finally removed but > could be put back if needed.
>> How is "connectedness" not required? Fielding says it's part of the >> essence of REST. > Connectedness was also analyzed but nobody seemed interested > in a collection of XML files that you have to explore to discover a > tiles > at the end.
> What is the real point on discovering tiles?
> In my opinion, tile systems that uses power of 2 related > scales to produce tiles can take advantage of this. > You can build a client that shows you the whole world > and the you can zoom in following the dependencies of > the corse tiles to the next detailed levels an so on. > That is exactly what google earth does with "superoverlays" [1].
> But the important questions is, why we have to explore > the tiles this way? Why simply can I start form a > low scale denominator and zoom out to a lower > resolution? Then the superresolution connectness of the tiles > is useless. And let me remain you that WMTS tiles > has not to follow the power of 2 relation.
> That is the real advantage of discovering tiles? > To index them in google search?, There could be > millions of them!. They are not searchable. They > are binary sequences to the computer.
The real point in discovering tiles is RESTful, not RPC, interaction. That's it.
"A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling]." [1]
"A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on- demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]" [1]
I'm not saying everyone has to use REST for this, just pointing out where REST is technically missing in the WMTS spec.
> That is the real advantage of discovering tiles?
> To index them in google search?, There could be
> millions of them!. They are not searchable. They
> are binary sequences to the computer.
Couldn't alternate representations of a tile be important? For
example, what about a GML representation - say the features which
touch a tile (I don't think anybody said it had to be an *exact*
representation=), or more precisely the parts of features which
intersect a tile at that scale say. Or an HTML representation? Would
it be breaking REST principles to have an html page which displayed
the tile in context? A map which is composed of many tiles would have
many bookmarks, but an html page which put the tile in the middle of
the map, say could be an alternative representation having one
bookmark. The html representation could contain a list of places that
could be indexed and hence discovered. I'm sure these ideas have
limitations in practise. Just askin'.
> "A REST API must not define fixed resource names or hierarchies (an
> obvious coupling of client and server). Servers must have the freedom
> to control their own namespace. Instead, allow servers to instruct
> clients on how to construct appropriate URIs, such as is done in HTML
> forms and URI templates, by defining those instructions within media
> types and link relations. [Failure here implies that clients are
> assuming a resource structure due to out-of band information, such as
> a domain-specific standard, which is the data-oriented equivalent to
> RPC's functional coupling]." [1]
> "A REST API should be entered with no prior knowledge beyond the
> initial URI (bookmark) and set of standardized media types that are
> appropriate for the intended audience (i.e., expected to be understood
> by any client that might use the API). From that point on, all
> application state transitions must be driven by client selection of
> server-provided choices that are present in the received
> representations or implied by the user’s manipulation of those
> representations. The transitions may be determined (or limited by) the
> client’s knowledge of media types and resource communication
> mechanisms, both of which may be improved on-the-fly (e.g., code-on-
> demand). [Failure here implies that out-of-band information is driving
> interaction instead of hypertext.]" [1]
I fail to see how WMTS violates either of these REST principles. The
only knowledge needed to use it is the initial URI (the capabilities
URI), the media type for the capabilities resource (which is XML,
extended with elements in the WMTS namespace) and the standardized
media types used by the tiles themselves (PNG, JPEG, etc). There are
just two mandatory application states, which could be called “Choose
Tile” (entered by retrieving the capabilities resource) and “Display
Tile” (entered by retrieving a tile resource”). The capabilities
resource presents the client with a list of tiles to choose from, and
tells clients how to construct the URI for each tile resource.
The tile URIs are not fixed resource names or hierarchies. A portion
of the tile URI is fixed and hierarchical, but in every scheme for
constructing a URI, a portion of the URI is necessarily fixed. A
hierarchical portion is just a special case of a fixed portion. For
example, consider a URI template that contains row and col
parameters. Row and col would necessarily be fixed in the sense that
only certain integers would be valid values for the parameters. A URI
template that contains a path parameter would not be any less valid,
and that is essentially what the WMTS scheme boils down to.
So, WMTS seems RESTful to me, as best as I can understand the term.
However, I have yet to see a clear set of rules to define the term.
Arguing whether the spec is RESTful may be about as meaningful as
arguing whether licorice tastes good.
>> That is the real advantage of discovering tiles? >> To index them in google search?, There could be >> millions of them!. They are not searchable. They >> are binary sequences to the computer.
> Couldn't alternate representations of a tile be important? For > example, what about a GML representation - say the features which > touch a tile (I don't think anybody said it had to be an *exact* > representation=), or more precisely the parts of features which > intersect a tile at that scale say. Or an HTML representation? Would > it be breaking REST principles to have an html page which displayed > the tile in context? A map which is composed of many tiles would have > many bookmarks, but an html page which put the tile in the middle of > the map, say could be an alternative representation having one > bookmark. The html representation could contain a list of places that > could be indexed and hence discovered. I'm sure these ideas have > limitations in practise. Just askin'.
> Cheers, > Peter Rushforth
Peter,
REST is indeed about opening up all kinds of new and different uses for resources.
Sean
-- Sean Gillies Software Engineer Institute for the Study of the Ancient World New York University
>> "A REST API must not define fixed resource names or hierarchies (an >> obvious coupling of client and server). Servers must have the freedom >> to control their own namespace. Instead, allow servers to instruct >> clients on how to construct appropriate URIs, such as is done in HTML >> forms and URI templates, by defining those instructions within media >> types and link relations. [Failure here implies that clients are >> assuming a resource structure due to out-of band information, such as >> a domain-specific standard, which is the data-oriented equivalent to >> RPC's functional coupling]." [1]
>> "A REST API should be entered with no prior knowledge beyond the >> initial URI (bookmark) and set of standardized media types that are >> appropriate for the intended audience (i.e., expected to be >> understood >> by any client that might use the API). From that point on, all >> application state transitions must be driven by client selection of >> server-provided choices that are present in the received >> representations or implied by the user’s manipulation of those >> representations. The transitions may be determined (or limited by) >> the >> client’s knowledge of media types and resource communication >> mechanisms, both of which may be improved on-the-fly (e.g., code-on- >> demand). [Failure here implies that out-of-band information is >> driving >> interaction instead of hypertext.]" [1]
> I fail to see how WMTS violates either of these REST principles. The > only knowledge needed to use it is the initial URI (the capabilities > URI), the media type for the capabilities resource (which is XML, > extended with elements in the WMTS namespace) and the standardized > media types used by the tiles themselves (PNG, JPEG, etc). There are > just two mandatory application states, which could be called “Choose > Tile” (entered by retrieving the capabilities resource) and “Display > Tile” (entered by retrieving a tile resource”). The capabilities > resource presents the client with a list of tiles to choose from, and > tells clients how to construct the URI for each tile resource.
I suppose one could make the case that URIs may be implied in the WMTS capability "Content" element, and that the construction rule involves traversing the XML tree to a TileMatrix and interpreting the range of width and height as individual tiles. If that's the way you want to go instead of using explicit URI templating, it should be formalized in the capabilities media type, and well documented. Perhaps as an XPath expression? Then instead of arguing about whether the service is RESTful, we can just start to clarify how clients use it in a RESTful manner.
> The tile URIs are not fixed resource names or hierarchies. A portion > of the tile URI is fixed and hierarchical, but in every scheme for > constructing a URI, a portion of the URI is necessarily fixed. A > hierarchical portion is just a special case of a fixed portion. For > example, consider a URI template that contains row and col > parameters. Row and col would necessarily be fixed in the sense that > only certain integers would be valid values for the parameters. A URI > template that contains a path parameter would not be any less valid, > and that is essentially what the WMTS scheme boils down to.
> So, WMTS seems RESTful to me, as best as I can understand the term. > However, I have yet to see a clear set of rules to define the term. > Arguing whether the spec is RESTful may be about as meaningful as > arguing whether licorice tastes good.
> - Chuck
I think it *could* be used RESTful. Just needs more formal specification and better documentation.
Sean
-- Sean Gillies Software Engineer Institute for the Study of the Ancient World New York University
> If that's the way you want to go
> instead of using explicit URI templating, it should be formalized in
> the capabilities media type, and well documented.
Are you saying that a custom media type would be needed? I don't
think that's necessary. I'll quote another one of Roy's bullets from
http://roy.gbiv.com/untangled/2008.
"A REST API should spend almost all of its descriptive effort in
defining the media type(s) used for representing resources and driving
application state, or in defining extended relation names and/or
hypertext-enabled mark-up for existing standard media types. ..."
I see WMTS capabilities as extended hypertext-enabled mark-up for an
existing standard media type (XML). Again, seems RESTful to me.
Practically speaking, using a custom media type would be counter
productive since it may prevent applications that don't understand
WMTS from treating it as XML. For example, IE wouldn't display it.
Regarding documentation, what is unclear about the way tile resources
are formed?
>> If that's the way you want to go >> instead of using explicit URI templating, it should be formalized in >> the capabilities media type, and well documented.
> Are you saying that a custom media type would be needed? I don't > think that's necessary. I'll quote another one of Roy's bullets from > http://roy.gbiv.com/untangled/2008.
> "A REST API should spend almost all of its descriptive effort in > defining the media type(s) used for representing resources and driving > application state, or in defining extended relation names and/or > hypertext-enabled mark-up for existing standard media types. ..."
> I see WMTS capabilities as extended hypertext-enabled mark-up for an > existing standard media type (XML). Again, seems RESTful to me.
> Practically speaking, using a custom media type would be counter > productive since it may prevent applications that don't understand > WMTS from treating it as XML. For example, IE wouldn't display it.
Sorry, I had the impression that OGC capabilities documents already used a custom media type other than text/xml. I'm wrong: the WMTS spec clearly says text/xml. Whether text/xml is too generic to be useful for content negotiation, or not, is often debated on rest-discuss. There are good arguments for using a custom type when your media has special processing rules like Atom's mustIgnore, hence application/atom +xml. The URI construction rules of WMTS don't affect XML processing and don't warrant a special media type, IMO.
The URI construction rules should be more formally specified in some OGC namespace, then. If the capabilities XML, and specifically the content section, *is* hypertext -- an assertion that hasn't appeared anywhere other than this thread -- let's make it clear.
> Regarding documentation, what is unclear about the way tile resources > are formed?
> - Chuck
The spec makes it clear how to make a GetResourceRepresentation request, yes. But it doesn't state what you're asserting here, that the service capabilities doc is a hypertext tile index. It doesn't encourage RESTful interaction with the service.
And then there's the question of whether layers, styles, tile matrix sets, and tile matrices are also resources. Are they? Will users treat them as they are, and will they invent representations for them if not officially specified?
Sean
-- Sean Gillies Software Engineer Institute for the Study of the Ancient World New York University
On Mar 26, 11:11 am, Sean Gillies <sean.gill...@gmail.com> wrote:
> And then there's the question of whether layers, styles, tile matrix
> sets, and tile matrices are also resources. Are they? Will users treat
> them as they are, and will they invent representations for them if not
> officially specified?
There are no resource representations defined for them, and they don't
have URL addresses. Whether or not that means they're not resources
is a matter of philosophy. These things could potentially be added to
the specification in the future should a practical need arise for it.
However, I see no compelling reason right now to complicate the
specification in this way. Really, it's okay to have a noun in the
specification without an XML resource representation being defined for
it.
