[Requests] Review and rewrite the requirements and tests in the ESRI proposed specifications 12-054 through 12-062

Adrian Custer ac at pocz.org
Mon Jul 23 12:54:02 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:
	All requirements and all tests

2. Implementation Specification Section number:
	All sections

3. Criticality:

4. Comments/justifications for changes:

The Requirements in the proposed specification are poorly written. They 
do not conform to the rules for clear specification documents required 
by the standard
	The Specification Model - A Standard for Modular specifications
which is currently required by all OGC specifications. Notably, 
requirements must:
	* be injunctions against a Standardization Target Type
	* be clear
	* be testable
to ensure good specifications are produced by the OGC.

As a single example suffices to demonstrate the lack of linguistic 
clarity that pervades the documents. Consider the very first requirement 
in the whole series of specifications:

     Req 1 If a request uses the HTTP GET method, the request SHALL
     be safe and idempotent.

which is to be tested by:

     A.1.1 Test: core/get
     Inspect the documentation to identify, if requests specified in
     the GeoServices REST API standard that support the HTTP GET method,
     are all safe and idempotent as specified in HTTP
     (RFC 2616, section 9.1).

This is hopelessly confused, let alone grammatically incorrect.

Clause 7 of this first proposed specification "Core" states that it 
"specifies principles that apply to all services" so, while the clause 
fails to state its Standardization Target Type, one can assume it to be 
a "Web Service" and, indeed, it must be if the various other documents 
are to define *extensions* of this core.

So it is the "web services" which are to have their behaviour 
constrained: it is *not* the "request" that "SHALL be" but the web 
service. The requirement is trying to impose that 'conformant web 
service instances' should handle particular requests in a particular 
manner. So far, it seems merely an issue of poor phrasing.

However, the issue is deeper. The requirement seems to enjoin conformant 
web service instances to handle all HTTP GET requests in a safe and 
idempotent manner. The former means that the user cannot be expected to 
know the request has any deleterious effects, and the latter means that 
the repetition of the request has no consequences. The HTTP standard, in 
section 9.1 "Safe and Idempotent Methods" states:

9.1 Safe and Idempotent Methods

9.1.1 Safe Methods

    Implementors should be aware that the software represents the user in
    their interactions over the Internet, and should be careful to allow
    the user to be aware of any actions they might take which may have an
    unexpected significance to themselves or others.

    In particular, the convention has been established that the GET and
    HEAD methods SHOULD NOT have the significance of taking an action
    other than retrieval. These methods ought to be considered "safe".
    This allows user agents to represent other methods, such as POST, PUT
    and DELETE, in a special way, so that the user is made aware of the
    fact that a possibly unsafe action is being requested.

    Naturally, it is not possible to ensure that the server does not
    generate side-effects as a result of performing a GET request; in
    fact, some dynamic resources consider that a feature. The important
    distinction here is that the user did not request the side-effects,
    so therefore cannot be held accountable for them.

9.1.2 Idempotent Methods

    Methods can also have the property of "idempotence" in that (aside
    from error or expiration issues) the side-effects of N > 0 identical
    requests is the same as for a single request. The methods GET, HEAD,
    PUT and DELETE share this property. Also, the methods OPTIONS and
    TRACE SHOULD NOT have side effects, and so are inherently idempotent.

    However, it is possible that a sequence of several requests is non-
    idempotent, even if all of the methods executed in that sequence are
    idempotent. (A sequence is idempotent if a single execution of the
    entire sequence always yields a result that is not changed by a
    reexecution of all, or part, of that sequence.) For example, a
    sequence is non-idempotent if its result depends on a value that is
    later modified in the same sequence.

    A sequence that never has side effects is idempotent, by definition
    (provided that no concurrent operations are being executed on the
    same set of resources).


These are *really* nice characteristics for services to have in response 
to GET requests. But note the "Naturally, it is not possible to 
ensure..." and "However, it is possible ..." phrasing in the respective 
sections which show us that these requirements are NOT TESTABLE.

If we look at the proposed test which starts "Inspect the document" we 
see right away that the test is not testing an instance of the 
Standardization Target Type! We should be trying to test a "web service 
instance!" The test gives no indication of how one could know the 
condition has been met.

Even worse, this is not a question of language, since if we actually try 
to come up with a test, we find that the test is not fixable. At best, 
we could require that, for every kind of GET request supported by the 
instance, the testing procedure select several specific requests and 
reissue each multiple times. That could, at least, potentially trigger a 
condition of non-safety or non-idempotence, if the implementation 
suffered from it. However, to verify that the requests had been handled 
safely or with idempotence, we would have to check that nothing of 
functional importance had been affected by these requests. Formally, we 
would at least have to repeat the entire suite of all tests before and 
after such repeated GET requests and compare the results to see if any 
of the answers had changed. But since the other requests might not be 
idempotent, that approach does not work either and we are stuck.

That particular injunction is untestable and therefore must be a 
recommendation not a requirement.

A similar analysis on the other requirements reveals a myriad of issues 
with the proposed specifications. The requirements need to be reviewed 
one by one, assessed for language, for the enjoined target, for the 
meaning of the injunction, and to establish how an implementor could 
know that the injunctions have or have not been met. The authors would 
be well served to adopt the pedantic but easy form of phrasing all 
requirements in the form:
     'Conformant <target type> (implementations) SHALL (qualifying
         clause) injunction'
for example
     Conformant tabular feature service implementations SHALL handle all
     messages sent to the <host> and <port> defined in every Service
     Endpoint URI defined by the service in conformance with the
     requirements for an 'origin server' in the HTTP/1.1 standard.
which provides a clear approach to each injunction. Then, the tests of 
each requirement must be reviewed, including writing a series of 
targeted specific tests which clarify the requirement and give 
implementors one source of validation.

These documents are not ready for publication by the OGC.

	Adrian Custer

More information about the Requests mailing list