[Requests] Review and rewrite the requirements and tests in the ESRI proposed specifications 12-054 through 12-062
ac at pocz.org
Mon Jul 23 12:54:02 EDT 2012
ac at pocz.org
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)
All requirements and all tests
2. Implementation Specification Section number:
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,
* 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
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.
More information about the Requests