[Requests] Change the shared title for clarity in the ESRI proposed specifications 12-054 through 12-062

Adrian Custer ac at pocz.org
Mon Jul 23 12:38:38 EDT 2012

Change Request


1. Evaluator:
	Adrian Custer
	ac at pocz.org

2. Submission:
	GeoServices REST API - Part 1: Core (12-054r1)
	GeoServices REST API - Part 3: Map Service (12-056r1)
	GeoServices ... - relationship with the OGC baseline (12-062r1)

	(12-054 through 12-062)


1. Requirement:
	None- The shared title of the specifications in the series:
		"GeoServices REST API"

2. Implementation Specification Section number:
	Title Page of each proposed specification

3. Criticality:

4. Comments/justifications for changes:

The proposed title shared by all the documents proposed by ESRI for 
adoption by the OGC, documents 12-054 through 12-062
	"GeoServices REST API"
should be changed for clarity prior to publication.

The proposed title is confusing, does not describe the true nature of 
the documents, and suggests the documents tackle a greater scope than 
they actually do, leading directly to interoperability issues and 
conflicting with the existing set of Web Services already standardized 
at the OGC.

Grammatically, the phrase suggest the specifications specify an API (a 
term which is never defined) but the formal requirements in the 
documents enjoin the Standardization Target Type "web service." Thus the 
documents are actually defining the behavior of web services in response 
to messages sent to those services. HTTP messages can be malformed in a 
myriad of ways that need to be adequately addressed by any web service 
standard, something that code APIs can avoid since language grammar 
checkers, pre-processors, compilers, or runtime engines will perform 
this fundamental checking. Thus a 'web API,' while a cute shorthand, 
does not adequately reflect the nature of what is needed in a 
standardization document.

The specifications to not specify a "REST API" since "REST" of course 
*not* a type of API but a characterization of the behaviour of a web 
service. Wikipedia calls it "a style of software architecture for 
distributed systems such as the World Wide Web", that is, a style of web 
services. So perhaps "REST Services" would be more accurate but since 
"REST" is never defined in the specification, even that is problematic. 
Many of the core issues motivating the concept of REST based service 
communication architecture are not discussed: while the services act 
like HTTP endpoints, it is not clear even that they are required to 
follow the HTTP standard, while the issues of caching resources are 
central to the discussion of REST, the issues are ignored by the 
proposed specifications, and while the impact of proxies central to the 
work of HTTP/1.1, HTTPbis, and REST, those issues are not considered by 
the documents. Indeed, the best justification given in the document is:
	{I}n general the patterns used in the GeoServices REST API
	can be found in the ... {"RESTful Web Services Cookbook"
	from Subbu Allamaraju}
which is to say that the document claims that its use of URL templates 
follows the pattern suggested by a REST book. Thus perhaps the documents 
propose 'HTTP Request Templates.' This is a long way from the notion of 
identifying the resources in the web architecture and building an 
architecture designed around the naming of those resources, the exchange 
of representations of those resources, and the update of those 
resources. The documents only consider partially these issues so that, 
in the specification, the word "REST" acts as more of a buzzword than as 
a concept put to useful work to solve interoperability issues.

The specifications do define "GeoServices" if those are 'services 
related to geo(graphy/spatial information/...) but so do all the other 
'web service specifications' at the OGC so one wonders why this word is 
given such prominence. The name probably made sense in the context of 
ESRI but no longer makes sense in the OGC context.

Jointly, the three words lead to confusion, since they seem to imply 
that these documents present the OGC wide approach to RESTful 
communication with OGC Web Services. However, that work is going on as 
separate efforts in the context of each respective SWGs. Almost all the 
OGC web services are being rewritten as new versions which are
     (1) more rigorously defined
     (2) better written
     (3) modular
with the latter explicitly aiming to provide the foundations to develop 
RESTful approaches.

Developing a clear title for the specification series will require 
getting at the essence of the nature of the document.

In actuality, these specifications describe the set of web services 
developed by ESRI, wrapped inside an OGC document. These web services 
suffer all of the problems of services developed by a single vendor 
without formal design, discussion during development, feedback during 
implementation, or harmonization work during standardization. The web 
services are ad-hoc, calling themselves one thing while dealing with 
others, e.g. a 'Map Service' that actually handles 'feature' queries and 
filters. Contributions towards standardization were explicitly refused 
during the development of this document since standardization would 
require harmonization with existing services which might require 
'backwards incompatible' changes with the existing ESRI services, a type 
of change refused outright by the SWG. (That ESRI retains copyright to 
the document even at the RFC stage suggests as well that this is *not* 
an OGC developed document but a production of ESRI.) So, really, these 
documents define the ESRI services and the title should reflect that, 
with "ESRI Web Services" but, of course, that begs the question of why 
this work is happening at the OGC. Absent the use of the 'ESRI' name in 
the title, these services need to be *clearly* distinguished from the 
existing services by using different names.

The specifications express the functionality of services dealing with 
geospatial entities with a simple conceptual model. This is made clear 
in the document "...Relation to the OGC Baseline" (12-062):
	However, for many use cases a simpler set of requirements is
	sufficient – and the GeoServices REST API addresses this market.
so that could become part of the ultimate title. The simplicity comes in 
two forms, first the conceptual model of the geospatial entities 
manipulated by the service is simple, i.e. it uses 'tabular features' 
('tabular' is used instead of 'simple' because 'simple features' have a 
problematic dual meaning: for some standards 'simple features' are 
features with a simple, flat list of attributes that can form a row in a 
table of all attributes but, in other standards, 'simple features' are 
features with a single spatial representation made of relatively simple 
vector geometries but potentially arbitrary non-spatial features). 
Secondly, the services offer only a limited amount of functionality. 
However, the latter could change over time by extension to the proposed 
specifications whereas the former aspect is central to the stated goal 
of this set of specifications. So the title should reflect this notion 
of 'Multipurpose Web Services for tabular features.'

The specifications also undertake a communication style which adopts 
some notions of the RESTful design although the purpose or advantage of 
what is adopted is never stated. The clients issue service requests 
using URL templates, the services use Javascript friendly message 
formats, and the service behaviour does consider idempotency and safety 
of requests to the server (more on that in the next change request). 
However, as stated above, only very limited consideration is made for 
the issues generally discussed under the banner of REST.

So, it seems that these specifications describe the behaviour of:
   * existing ESRI implementations,
   * web services,
   * multipurpose services,
   * services using a simplified model of geospatial features that
     have linear interpolated vector based spatial descriptions and
     tabular attributes,
   * services that accept requests to endpoints defined using
     URL templates,
   * services that favour JSON, and
   * services that have functionality defined in various extensions.
Indeed, it is actually unclear why this is not a single service, say the 
"Multipurpose Tabular Feature Service" with many kind of interactions, 
say the "Map Requests for the Multipurpose Tabular Feature Service" and 
the "Data Requests for the Multipurpose Tabular Feature Service".

Given this nature, it should be possible to develop a shared title which 
better reflects the nature of the documents, which does not imply more 
than the candidate specifications offer, and which distinguish the 
contribution of the proposed specifications from the currently published 
standards. I am sure the authors could, if they chose to do so, find a 
title pleasing to them and less confusing to the whole community.

	Adrian Custer

More information about the Requests mailing list