Best Practices SOS HTTP GET Request

Introduction

An HTTP request could be of various types: GET, POST, PUT etc., as explain in the RFC 2616. GET passes parameters to the server in the HTTP URL (e.g. http://marinemetadata.org:9600/oostethys/sos?VERSION=1.0.0&SERVICE=SOS&REQUEST=GetCapabilities). POST sends a document to the server, allowing an message or result to be returned,  or to provide a block of XML data, among others.

At OOSTethys we found that the GET request is very popular in the oceanographic community, because it is well-understood, easier to implement and easier to query. Sensor Observation Service, however,  does not explicitly use a GET request. This section explains the GET request operations supported by OOSTethys Sensor Observation Service cookbooks. The information presented here was mostly extracted from OGC specifications and in some cases clarifications and minor comments were added. If not noted, this section complies with the OGC Web Services Common Specification 1.1.0 (OGC 06-121r3) and the Sensor Observation Service Specification 1.0 (OGC 06-009r6). If there are discrepancies between the specification and the schema, the schema is preferred.

The document first presents the general structure of a GET request, notes about how to handle special characters and capitalization rules. Then, the document presents the GET request details for each of the Sensor Observation Service (SOS) supported by OOSTethys, which correspond to the three mandatory operations in a Sensor Observation Service (SOS):

• GetCapabilities: returns general metadata about the service, operations supported and list of observation offerings.
• DescribeSensor: returns metadata about a sensor system. It could be an observing system, platform or a simple device, such as a bin. The return is given as a SensorML or TML document
• GetObservation: returns a collection of observations. each observation is composed of metadata, description of the phenomena being returned (parameter names, units of measure, reference systems) and values.

Structure of the GET request

The structure of the operation is specified in Table 34 (Whiteside, 2007).

Reserved characters

Capitalization of Keyword Value Pair (KVP) names and values

• Parameter names are case insensitive. The following example shows equivalent terms for a parameter named “request”: REQUEST, request, Request, or ReQuEsT. As a guideline, it is suggested that lowercase names be used for ease-of-reading and consistency.
• Parameter values are case sensitive and string values are UpperCamelCase. These are appropriate examples for parameter values: GetObservation, DescribeSensor.
  

Escaping special characters

IETF 2396 , section 2.4.1 explains that special characters should be escaped as follows: percent character "%" followed by the two hexadecimal digits.  This is important because both URIs, and URNs could be sent as values for parameters, and they may include special characters . An online application that helps to convert special characters to escaped characters could be found here.

GetCapabilities Get Request

The parameters rules for the getCapabilities operation are taken from table 3 and table 5 of OGC 06-121r3

Example: http://host[:port]/path?request=GetCapabilities&version=1.0.0&service=sos

DescribeSensor Request

The attributes of the DescribeSensor request are detailed in the Table 3 of the Sensor Observation Service specification 1.0 (OGC 06-009r6).

GetObservation Request

The attributes of the GetObservation request are detailed in the Table 4 of the Sensor Observation Service specification 1.0 (OGC 06-009r6). Here is presented a summary of the ones used by OOSTethys.

References

• Whiteside, A., Ed. 2007, OGC Web Services Common Specification, Open Geospatial Consortium Inc. , OGC 06-121r3 [pdf]
  
  
• Na, A. and Priest, M., Eds, 2007, Sensor Observation Service, Open Geospatial Consortium Inc. , OGC 06-009r6. [pdf]
  
  

Revision History

TODOs