proposal to replace eventid query in FDSN Event ws
Philip Crotwell
I would like to propose that the eventid query param in the FDSN Event
web service be deprecated and in its place a new "service method" be
created for getting a single event by its publicID. It would look
something like this:
http://service.example.org/fdsnws/event/2/publicid/<identifier>?<parameters>
The parameters for this service method would be limited to
nodata, format, includeallorigins, includeallmagnitudes and includearrivals.
The event identifier is not a parameter but is part of the URL path.
An example URL where the publicID in a query is "quakeml:abc/123"
would be:
http://service.example.org/fdsnws/event/2/publicid/abc/123?includeallorigins=true
Also, there must be a simple 1:1 mapping between the single event
service method URL and the publicID of each quakeml event returned in
a general query. Thus, it is required that in a quakeml response from
the more general query service method, the publicID on each event must
be of the form:
quakeml:⟨authority-id⟩/⟨resource-id⟩
where authority-id and resource-id follow the quakeml specification
but with the restriction that they are URL-friendly (ie mostly
alphanumberic plus - . _ and ~ ), but allowing for additional /
characters in the resource if a hierarchy is desired. No characters
that require the client to process the publicID before creating the
URL are allowed. See this RFC for URL/URI spec, in particular the
"unreserved" characters in section 2.3.
https://www.ietf.org/rfc/rfc3986.txt
For example the USGS might use "quakeml:usgs/us/c000lvb5" which would map to
http://earthquake.usgs.gov/fdsnws/event/2/publicid/usgs/us/c000lvb5
or while ETHZ might use
"quakeml:ch.ethz.sed/sc3a/2017eemfch" which would map to
http://arclink.ethz.ch/fdsnws/event/2/publicid/ch.ethz.sed/sc3a/2017eemfch
Basically everything after the "quakeml:" is the identifier for this
service. This allows a client to easily take a publicID, trim off the
initial "quakeml:" and go back to the service to recover the single
event without complex processing.
The reasoning:
1) The current "access a single event" method using eventid is
currently under-specified, especially related to the publicID, and so
each implementation has done it slightly differently. Resolving this
should be done in a backwards compatible way, which means deprecating
the current query eventid parameter and replacing it with a new method
to access this.
2) When asking for a single event where an unique identifier is known,
none of the other query parameters make sense. There is no reason to
specify a mag range or time range once you know the identifier. Either
you have a valid identifier and receive a single event, or you don't
and get a nodata response. Using a separate service method allows a
separation of parameters that are appropriate from those that don't
for each type, general query versus single event access.
3) When asking for a single event, the identifier is not optional, and
so should part of the URL path and not a parameter. The existing
QuakeML publicID as used by current datacenters for the most part fits
with this style.
4) PublicIDs should not be large URIs that attempt to look like a
event web service query URL as that is overly verbose, confusing and
adds complexity to the client without actually helping.
Would be interested in any comments.
thanks
Philip