Forgot your password?
New user?
Experiment #1
OGC® Ocean Science IE Report has been submitted to OGC
Ocean Innovation 2008 – “World Summit – Ocean Observing Systems”
Document Actions
Best Practices- Support of HTTP Get Requests - discussion page
The SOS 1.0 specification defines HTTP POST requests but is silent on the use of HTTP Get requests. Working with the IOOS DIF SOS effort we are recommending to the OGC that support for GET methods be added.
Support for GET METHOD
BBOX - summary of discussion June 13, 2008
In the SOS spec, Table 4 defines GetObservation parameters but does not define
a URL syntax for use with HTTP GET. FeatureOfInterest is a parameter in the
table, but BBOX is not. During the 2008 June 13 telecon, we discussed three
possible ways of specifying a bounding box using HTTP GET:
(1) Ignore featureOfInterest parameter in SOS Table 4, use BBOX parameter (as in WMS and WFS):
BBOX=x0,y0,x1,y1
(2) Use featureOfInterest parameter, and put the BBOX within it (as in the HTTP POST XML case):
featureOfInterest=BBOX:x0,y0,x1,y1
(3) Use featureOfInterest parameter to declare that this request contains a BBOX rather than
the ID of a FOI, and then use separate BBOX parameter to enumerate coordinate values:
featureOfInterest=BBOX & BBOX=x0,y0,x1,y1
OOSTethys is using #1. NOAA IOOS DIF project is using #2. #3 is either the best or the worst
of both worlds.
We did not reach a conclusion regarding the best approach.
Current OOSTethys SOS Cookbooks, SOS 0.0.3 and 1.0, support HTTP GET requests along the following lines.
All Requests
All the names in the name value pairs are case insensitive and can include mixed case. But the actual values are case sensitive.
SERVICE = SOS *
REQUEST = GetCapabilities | DescribeSensor | GetObservation *
VERSION =1.0 *
RESPONSEFORMAT = text/xml; subtype om/1.0 *
DescribeSensor
PROCEDURE = <sensor_id> *GetObservation
OFFERING = sensor_id *OBSERVEDPROPERTY = propetry1, porperty2, ... *
SRSNAME=EPSG:4329 *
TIME = time1 time instant
TIME = time1/time2 time range
BBOX = minlon,minlat,maxlon,maxlat
* required
Some Examples
request=GetObservation&offering=ALL_PLATFORMS&observedProperty=air_temperature&bbox=-71.50,39.0,-63.0,40.0
request=GetObservation&offering=A01&observedProperty=sea_water_speed,direction_of_sea_water_velocity
request=GetObservation&offering=C02&observedProperty=sea_water_salinity&time=2008-04-10T10:00:00Z/2008-04-12T11:00:00Z
Questions arising from ongoing discussions with the IOOS DIF Group
To more closely match the POST specifications should time become eventTime?
Should BBOX be specified as the featureOfInterest featureOfInterest=BBOX:minlat,minlon,maxlat,maxlon SRSName=EPSG:code
What should the responseFormat specification be?
IOOS DIF Group Discussions
Posted: Thursday, May 29, 2008 by Jeff de La Beaujardiere
3:50 PM EDT
When the GetObservation request is expressed using XML sent via HTTP
POST, this is what the bounding box looks like (from SOS v1.0, clause
8.4.5.3 "Example3 – Request With Bounding Box"):
<sos:featureOfInterest>
<ogc:BBOX>
<ogc:PropertyName>gml:location</ogc:PropertyName>
<gml:Envelope>
<gml:lowerCorner>38.11 -78.6</gml:lowerCorner>
<gml:upperCorner>38.14 -78.4</gml:upperCorner>
</gml:Envelope>
</ogc:BBOX>
</sos:featureOfInterest>
If the request is encoded in a URL using HTTP GET, it seems like at least
some implementations (OOSTethys?) have used the shortcut
BBOX=minlon,minlat,maxlon,maxlat. The UMN Mapserver implementation, on
the other hand, encodes the XML for the feature of interest in the
request parameter:
(see http://mapserver.gis.umn.edu/docs/howto/sos_server/#getobservation-request .
This in-line XML seems very
cumbersome, and perhaps you even need to escape '<' and '>' using
'<' and '>', so I can understand why the shortcut 'BBOX'
was used.
| Subject: | Re: HTTP GET format for SOS requests? |
| Posted: | Monday, June 02, 2008 by Jeff de La Beaujardiere 4:04 PM EDT |
| In Reply To: | HTTP GET format for SOS requests? (posted by Jeff de La Beaujardiere) |
I attended part of the joint Oceans Interoperability Experiment/OOSTethys on 2008-05-29.
We discussed the need for an HTTP GET specification for SOS GetObservation requests,
and all agreed it was desirable.
We felt that our two groups (IOOS DIF and Oceans.IE) should come to some agreement on what the request would look like, and then circulate that proposal more broadly. NDBC & CO-OPS would probably need to start using the proposal even before it has been fully circulated because they need some way to allow users to ask for data.
This is my initial suggestion for the request parameters, with explanation and notes below.
I offer this for discussion, and welcome any comments or criticism.
-Jeff DLB
===DRAFT OF PROPOSED HTTP GET REQUEST FOR SOS GetObservation===
Request parameters:
SERVICE=SOS
VERSION=1.0.0
REQUEST=GetObservation
OFFERING=sensorID
OBSERVEDPROPERTY=observedProperty1
RESULTFORMAT=application/ioos+xml;version=0.6.0
EVENTTIME=time1 (or time1/time2 for a time range)
SRSNAME=urn:ogc:def:crs:OGC:1.3:CRS84
FEATUREOFINTEREST=BBOX:min_lon,min_lat,max_lon,max_lat
The actual URL would look something like http://www.ndbc.noaa.gov/something?SERVICE=SOS&VERSION=1.0.0&etc...
All parameter names (SERVICE, VERSION, etc) are case-INsensitive.
Parameter values are generally case sensitive, because they are copies of
allowed values from the data provider's service metadata.
* Service, version, request parameters are mandatory and have the values shown above (or the appropriate version number if not SOS v1.0.0).
* Offering (mandatory) is one of the "offerings" in your service metadata. It could, for example, be a concatenated sensor ID such as 'NDBC:42002:ADCP1'.
* ObservedProperty (mandatory) is the name of the variable requested.
* ResultFormat (mandatory) is the MIME type of the desired output format.
NOTE 1: 'text/xml' is a very vague MIME type, so something more specific is generally recommended.
I would suggest something like
RESULTFORMAT=application/ioos+xml;version=0.6.0
for the following reasons.
I think OOSTethys has been using application/com-xml, and UMN Mapserver seems to use text/xml;subtype=”om1.0.30”.
However, RFC3023 (http://www.ietf.org/rfc/rfc3023.txt) says we should use application/<something>+xml .
Furthermore, RFC 1341 (http://www.faqs.org/rfcs/rfc1341.html) says the "subtype" is the part
after the '/' in MIME: Content-Type := type "/" subtype *[";" parameter]
Finally, the O&M spec leaves a lot of latitude about what the XML actually looks like, so
'om1.0.3' may not be specific enough as a parameter.
* EventTime (optional): time of desired data in ISO8601 format: yyyy-mm-ddThh:mm.
Single time -> send data for the requested time.
time1/time2 -> send data for the requested range (inclusive of endpoints).
no value give -> send lastest available data.
NOTE 2: I suggest the time *not* be enclosed in XML for HTTP GET requests.
This follows the spirit of SOS, but not the letter of Table 4.
This is one of the things we would eventually want to circulate to OGC, and perhaps make part of a formal Change Request for SOS.
* SRSname (optional) is the identifier of the Coordinate Reference System used for bounding box coordinates.
Two possible values of interest are urn:ogc:def:crs:OGC:1.3:CRS84 (longitude, then latitude
in WGS84 [World Geodetic System 1984]).
or urn:ogc:def:crs:EPSG:6.6:4326 (WGS84 latitude, then longitude).
Your server can state in its service metadata what CRS(es) you support, and you are not required
to support more than one. You must issue an Exception message if the request includes a CRS you
do not support.
I recommend supporting at least urn:ogc:def:crs:OGC:1.3:CRS84 (WGS84 longitude, then latitude).
* FeatureOfInterest (optional) is, for now, a container for the bounding box (BBOX) of the request
(expressed in units and axes appropriate to SRSname). Eventually, it could be other feature IDs
(e.g., geographic regions) named in the service metadata.
BBOX would only be used if the server can support subsetting and aggregation based on bounding box.
It is a list of four values representing the minimum value of axis 1, the minimum of axis 2, the
maximum of axis 1, and the maximum of axis 2.
If CRS84 is used, then the order is min_lon,min_lat,max_lon,max_lat.
If EPSG:4326 is used, then the order is min_lat,min_lon,max_lat,max_lon.
NOTE 3: The SOS spec does not define a BBOX argument as such. The spec says there is an optional
featureOfInterest parameter, which may contain a BBOX. In the HTTP POST XML case, the BBOX would
be expressed in XML. OOSTethys simply uses 'BBOX'. UMN Mapserver, on the other hand, uses featureOfInterest
with XML directly embedded in the HTTP GET URL. Neither of these seem satisfactory.
I am suggesting here that we (a) use FeatureOfInterest as the name of the parameter, for consistency
with SOS and (b) allow a shortcut definition of BBOX of the form BBOX:min_lon,min_lat,max_lon,max_lat
for efficient representation in HTTP GET.
We discussed the need for an HTTP GET specification for SOS GetObservation requests,
and all agreed it was desirable.
We felt that our two groups (IOOS DIF and Oceans.IE) should come to some agreement on what the request would look like, and then circulate that proposal more broadly. NDBC & CO-OPS would probably need to start using the proposal even before it has been fully circulated because they need some way to allow users to ask for data.
This is my initial suggestion for the request parameters, with explanation and notes below.
I offer this for discussion, and welcome any comments or criticism.
-Jeff DLB
===DRAFT OF PROPOSED HTTP GET REQUEST FOR SOS GetObservation===
Request parameters:
SERVICE=SOS
VERSION=1.0.0
REQUEST=GetObservation
OFFERING=sensorID
OBSERVEDPROPERTY=observedProperty1
RESULTFORMAT=application/ioos+xml;version=0.6.0
EVENTTIME=time1 (or time1/time2 for a time range)
SRSNAME=urn:ogc:def:crs:OGC:1.3:CRS84
FEATUREOFINTEREST=BBOX:min_lon,min_lat,max_lon,max_lat
The actual URL would look something like http://www.ndbc.noaa.gov/something?SERVICE=SOS&VERSION=1.0.0&etc...
All parameter names (SERVICE, VERSION, etc) are case-INsensitive.
Parameter values are generally case sensitive, because they are copies of
allowed values from the data provider's service metadata.
* Service, version, request parameters are mandatory and have the values shown above (or the appropriate version number if not SOS v1.0.0).
* Offering (mandatory) is one of the "offerings" in your service metadata. It could, for example, be a concatenated sensor ID such as 'NDBC:42002:ADCP1'.
* ObservedProperty (mandatory) is the name of the variable requested.
* ResultFormat (mandatory) is the MIME type of the desired output format.
NOTE 1: 'text/xml' is a very vague MIME type, so something more specific is generally recommended.
I would suggest something like
RESULTFORMAT=application/ioos+xml;version=0.6.0
for the following reasons.
I think OOSTethys has been using application/com-xml, and UMN Mapserver seems to use text/xml;subtype=”om1.0.30”.
However, RFC3023 (http://www.ietf.org/rfc/rfc3023.txt) says we should use application/<something>+xml .
Furthermore, RFC 1341 (http://www.faqs.org/rfcs/rfc1341.html) says the "subtype" is the part
after the '/' in MIME: Content-Type := type "/" subtype *[";" parameter]
Finally, the O&M spec leaves a lot of latitude about what the XML actually looks like, so
'om1.0.3' may not be specific enough as a parameter.
* EventTime (optional): time of desired data in ISO8601 format: yyyy-mm-ddThh:mm.
Single time -> send data for the requested time.
time1/time2 -> send data for the requested range (inclusive of endpoints).
no value give -> send lastest available data.
NOTE 2: I suggest the time *not* be enclosed in XML for HTTP GET requests.
This follows the spirit of SOS, but not the letter of Table 4.
This is one of the things we would eventually want to circulate to OGC, and perhaps make part of a formal Change Request for SOS.
* SRSname (optional) is the identifier of the Coordinate Reference System used for bounding box coordinates.
Two possible values of interest are urn:ogc:def:crs:OGC:1.3:CRS84 (longitude, then latitude
in WGS84 [World Geodetic System 1984]).
or urn:ogc:def:crs:EPSG:6.6:4326 (WGS84 latitude, then longitude).
Your server can state in its service metadata what CRS(es) you support, and you are not required
to support more than one. You must issue an Exception message if the request includes a CRS you
do not support.
I recommend supporting at least urn:ogc:def:crs:OGC:1.3:CRS84 (WGS84 longitude, then latitude).
* FeatureOfInterest (optional) is, for now, a container for the bounding box (BBOX) of the request
(expressed in units and axes appropriate to SRSname). Eventually, it could be other feature IDs
(e.g., geographic regions) named in the service metadata.
BBOX would only be used if the server can support subsetting and aggregation based on bounding box.
It is a list of four values representing the minimum value of axis 1, the minimum of axis 2, the
maximum of axis 1, and the maximum of axis 2.
If CRS84 is used, then the order is min_lon,min_lat,max_lon,max_lat.
If EPSG:4326 is used, then the order is min_lat,min_lon,max_lat,max_lon.
NOTE 3: The SOS spec does not define a BBOX argument as such. The spec says there is an optional
featureOfInterest parameter, which may contain a BBOX. In the HTTP POST XML case, the BBOX would
be expressed in XML. OOSTethys simply uses 'BBOX'. UMN Mapserver, on the other hand, uses featureOfInterest
with XML directly embedded in the HTTP GET URL. Neither of these seem satisfactory.
I am suggesting here that we (a) use FeatureOfInterest as the name of the parameter, for consistency
with SOS and (b) allow a shortcut definition of BBOX of the form BBOX:min_lon,min_lat,max_lon,max_lat
for efficient representation in HTTP GET.
| Subject: | Re[3]: HTTP GET format for SOS requests? |
| Posted: | Monday, June 02, 2008 by Jeff de La Beaujardiere 5:06 PM EDT |
| In Reply To: | Re[2]: HTTP GET format for SOS requests? (posted by Armin Pruessner) |
[Armin wrote:
Is there a reason why the eventTime format is different from the IOOS-DIF schema format?
* EventTime (optional): time of desired data in ISO8601 format: yyyy-mm-ddThh:mm.
instead of yyyy-mm-ddThh:mm:ssZ?]
Sorry, I left off the trailing 'Z' which is mandatory if time is UT.
However, seconds are not mandatory in ISO8601, and I think observation times are not necessarily known to the nearest second, or are not advertised as such when the reporting
frequency is >>1sec (e.g., for 360sec=6min data).
Therefore, I think you should (a) include the trailing 'Z' and (b) express times to whatever precision is reasonable.
Daniel et al., does the DCS mandate the use of seconds in time values?
ISO8601 allows truncation from the right of unneeded elements, so that all of the following are legal: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-ddThh, yyyy-mm-dd-Thh:mm, yyyy-mm-ddThh:mm:ss.sss (all with trailing 'Z' or local time zone specifier).
[Armin wrote:
Also, you specified that the parameter names should NOT be case-sensitive for the HTTP/GET. They are however case-sensitive for XML (XML element names in general are case sensitive). Would this cause confusion for users? From an implementation side, it would be nice to treat GET and POST input validation in the same manner.]
In OGC Web Services, when there are name=value pairs in requests, the name is generally not case sensitive whereas the value is. You are correct that if the 'name' appeared as an element name in an XML-formatted request then it would be case-sensitive. I do not know whether OGC has any language about that point.
I recommend that you accept names case-insensitively. In practice, many servers follow the Robustness Principle ( http://en.wikipedia.org/wiki/Robustness_Principle ) of "Be conservative in what you do; be liberal in what you accept from others," and are often lenient about accepting values case-insensitively as well.
Is there a reason why the eventTime format is different from the IOOS-DIF schema format?
* EventTime (optional): time of desired data in ISO8601 format: yyyy-mm-ddThh:mm.
instead of yyyy-mm-ddThh:mm:ssZ?]
Sorry, I left off the trailing 'Z' which is mandatory if time is UT.
However, seconds are not mandatory in ISO8601, and I think observation times are not necessarily known to the nearest second, or are not advertised as such when the reporting
frequency is >>1sec (e.g., for 360sec=6min data).
Therefore, I think you should (a) include the trailing 'Z' and (b) express times to whatever precision is reasonable.
Daniel et al., does the DCS mandate the use of seconds in time values?
ISO8601 allows truncation from the right of unneeded elements, so that all of the following are legal: yyyy, yyyy-mm, yyyy-mm-dd, yyyy-mm-ddThh, yyyy-mm-dd-Thh:mm, yyyy-mm-ddThh:mm:ss.sss (all with trailing 'Z' or local time zone specifier).
| Subject: | Re[3]: HTTP GET format for SOS requests? |
| Posted: | Monday, June 02, 2008 by Jeff de La Beaujardiere 5:13 PM EDT |
| In Reply To: | Re[2]: HTTP GET format for SOS requests? (posted by Armin Pruessner) |
Also, you specified that the parameter names should NOT be case-sensitive for the HTTP/GET. They are however case-sensitive for XML (XML element names in general are case sensitive). Would this cause confusion for users? From an implementation side, it would be nice to treat GET and POST input validation in the same manner.]
In OGC Web Services, when there are name=value pairs in requests, the name is generally not case sensitive whereas the value is. You are correct that if the 'name' appeared as an element name in an XML-formatted request then it would be case-sensitive. I do not know whether OGC has any language about that point.
I recommend that you accept names case-insensitively. In practice, many servers follow the Robustness Principle ( http://en.wikipedia.org/wiki/Robustness_Principle ) of "Be conservative in what you do; be liberal in what you accept from others," and are often lenient about accepting values case-insensitively as well.
| Subject: | Re[5]: HTTP GET format for SOS requests? |
| Posted: | Monday, June 02, 2008 by Armin Pruessner 5:41 PM EDT |
| In Reply To: | Re[4]: HTTP GET format for SOS requests? (posted by Mike Garcia) |
I would encourage IOOS-DIF to use a the generic "text/xml" MIME TYPE with some sort of subtype (or other designation), such as
text/xml;subtype="ioos/0.6.0"
If you specify the MIME type as some sort of uncommon format like application/ioos+xml then most browsers such as IE or Firefox will give you a security warning complaining about an unknown file type. Although SOS is mostly a business-to-business application, using "application/ioos+xml " is definitely a detriment to useability in terms of new users viewing the data via the web.
The IOOS-DIF format is in fact just generic text/xml. The "application/..." MIME type is usually reserved for binary files for well-known applications.
For the first release, CO-OPS will implement the MIME as text/xml until this issue is more thoroughly investigated.
Thanks.
-Armin
[Armin wrote: I would encourage IOOS-DIF to use a the generic "text/xml" MIME TYPE with some sort of subtype (or other designation), such as text/xml;subtype="ioos/0.6.0"]
Armin-
You raise a good point--I had forgotten about that issue with MIME types of the form application/something+xml. Unfortunately, the dilemma is that 'application/something+xml' is the "right" thing to do, but 'text/xml' works better when the client is a browser.
When I started typing this response, I was planning to say "Let's use text/xml," but now I would like to offer a different suggestion:
Have your server support both. Specifically, you would allow both 'text/xml' and 'application/ioos+xml;version=0.6.0' in the GetObservation request, and you would list both as supported formats in your service metadata, but the actual XML sent would be the same in both cases. Only the HTTP Content-type header would differ in your response.
I make this dual-support suggestion for several reasons:
- Simple clients can make use of the text/xml type.
- Sophisticated users can configure their system to dispatch the content to the thick client of their choice by requesting the application/ type.
- The reasons enumerated in RFC 3023, which proposed the '+xml' designation.
- IANA (Internet Assigned Numbers Authority) will not accept registration of a parameterized text/xml MIME type, but they will accept application/something+xml (see RFC 4289, which normatively references RFC 3023).
- There is useful precedent for the +xml type; it is used by KML, ATOM, RDF, SVG, SMIL, SOAP, WSDL, and XHTML, among others (see http://www.iana.org/assignments/media-types/application/ ).
Is this "support both" idea crazy, or can you live with it?
I know that my own WMS implementations would discreetly accept 'text/plain' as a format argument for GetCapabilities when I just wanted to see the XML.
If we do use, either alone or not, a text/xml variant, then I have one more suggestion. Your proposal of text/xml;subtype="ioos/0.6.0" is in line with UMN Mapserver's use of text/xml;subtype=”om1.0.30”. My only concern with it is the word 'subtype', because technically the MIME string is composed of type/subtype (so 'xml' is already the "subtype"); after the semicolon are zero or more "parameters." Accordingly, I would suggest something like
text/xml; encoding="ioos/0.6.0"
or
text/xml; schema="ioos/0.6.0".
Regards,
Jeff DLB
text/xml;subtype="ioos/0.6.0"
If you specify the MIME type as some sort of uncommon format like application/ioos+xml then most browsers such as IE or Firefox will give you a security warning complaining about an unknown file type. Although SOS is mostly a business-to-business application, using "application/ioos+xml " is definitely a detriment to useability in terms of new users viewing the data via the web.
The IOOS-DIF format is in fact just generic text/xml. The "application/..." MIME type is usually reserved for binary files for well-known applications.
For the first release, CO-OPS will implement the MIME as text/xml until this issue is more thoroughly investigated.
Thanks.
-Armin
| Subject: | Re[6]: HTTP GET format for SOS requests? |
| Posted: | Monday, June 02, 2008 by Jeff de La Beaujardiere 11:14 PM EDT |
| In Reply To: | Re[5]: HTTP GET format for SOS requests? (posted by Armin Pruessner) |
Armin-
You raise a good point--I had forgotten about that issue with MIME types of the form application/something+xml. Unfortunately, the dilemma is that 'application/something+xml' is the "right" thing to do, but 'text/xml' works better when the client is a browser.
When I started typing this response, I was planning to say "Let's use text/xml," but now I would like to offer a different suggestion:
Have your server support both. Specifically, you would allow both 'text/xml' and 'application/ioos+xml;version=0.6.0' in the GetObservation request, and you would list both as supported formats in your service metadata, but the actual XML sent would be the same in both cases. Only the HTTP Content-type header would differ in your response.
I make this dual-support suggestion for several reasons:
- Simple clients can make use of the text/xml type.
- Sophisticated users can configure their system to dispatch the content to the thick client of their choice by requesting the application/ type.
- The reasons enumerated in RFC 3023, which proposed the '+xml' designation.
- IANA (Internet Assigned Numbers Authority) will not accept registration of a parameterized text/xml MIME type, but they will accept application/something+xml (see RFC 4289, which normatively references RFC 3023).
- There is useful precedent for the +xml type; it is used by KML, ATOM, RDF, SVG, SMIL, SOAP, WSDL, and XHTML, among others (see http://www.iana.org/assignments/media-types/application/ ).
Is this "support both" idea crazy, or can you live with it?
I know that my own WMS implementations would discreetly accept 'text/plain' as a format argument for GetCapabilities when I just wanted to see the XML.
If we do use, either alone or not, a text/xml variant, then I have one more suggestion. Your proposal of text/xml;subtype="ioos/0.6.0" is in line with UMN Mapserver's use of text/xml;subtype=”om1.0.30”. My only concern with it is the word 'subtype', because technically the MIME string is composed of type/subtype (so 'xml' is already the "subtype"); after the semicolon are zero or more "parameters." Accordingly, I would suggest something like
text/xml; encoding="ioos/0.6.0"
or
text/xml; schema="ioos/0.6.0".
Regards,
Jeff DLB