SOS SPS REST

REST Bindings for SOS/SPS

Requirements

SOS needs to expose the following resources:

• Service Capabilities (service info, offerings?)
• Procedures/Offerings
• Procedure Descriptions (history)
• Features of Interest (GeoJSON w/ CRS)
• Observations
• Data Streams

In addition, SPS needs to expose:

• Tasks and their status
• Control Streams

URLs

The following URL hierarchy can be used to access SOS resources in a REST fashion:

Root is http://domain/endpoint/v2

URL		Resource Type	Filtering
/		Service Info
/procedures		Procedure[]	time (of availability), geo, text
/procedures/{id}		Procedure
	/descriptionHistory (desc)	AbstractProcess[] as SML-JSON	time
	/descriptionHistory/latest	AbstractProcess as SML-JSON
	/descriptionHistory/{idx*}	AbstractProcess as SML-JSON
	/featuresOfInterest (fois)	Feature[] as GeoJSON	time, geo
	/featuresOfInterest/latest	Feature[] as GeoJSON	geo
	/featuresOfInterest/{id}	Feature as GeoJSON
	/observations (obs)	Observation[] as OM-JSON	time, foi, obsprop, geo
	/observations/{id}	Observation as OM-JSON
	/observations/latest	Observation as OM-JSON
	/dataStreams (streams)	DataStream[] as SWE-JSON
	/dataStreams/{id**}	DataStream as SWE-JSON
	/dataStreams/{id}/past	SWE Record[] (csv, json or binary)	time, foi, obsprop, geo
	/dataStreams/{id}/latest	SWE Record (csv, json or binary)	foi, obsprop, geo
	/dataStreams/{id}/live	SWE Record[] (csv, json or binary)	foi, obsprop, geo
For Tasking
	/tasks	Task[]	time
	/tasks/{id}	Task
	/tasks/{id}/status	TaskStatus
	/controlStreams/{id}	DataStream as SWE-JSON
	/controlStreams/{id}/	DataStream as SWE-JSON

| /featuresOfInterest (fois) | Feature[] as GeoJSON | proc, geo, time, text | | | /featuresOfInterest/{id} | Feature as GeoJSON | | | | /observations (obs) | Observation[] as OM-JSON | time, proc, foi, obsprop, geo | | /observations/{id} | Observation as OM-JSON | |

(*) idx is 0 for latest, and increment as we're going back in time

(**) reserved data stream names: 'location', 'status'

Paging is allowed on all collections (i.e. procedures, descriptionHistory, fois, observations, records).

Resources

Service Info

{
  "title": "service title",
  "abstract": "service abstract",
  "keywords": [],
  "serviceType": "SOS",
  "version": "2.0.0",
  "profiles": [],
  "fees": "",
  "accessConstraints": "",
  "provider": {
    "name": "company name",
    "contactInfo": {
      "individualName": "Bob Jones",
      "address": {
        ...
      }
    }
  },
  "@procedures": "./procedures",
  "@featuresOfInterest": "./fois",
  "@observations": "./obs"
}

Procedure/Offering

{
  "numId": "1",
  "id": "temp_sensors",
  "uid": "urn:org:sensor:001",
  "parentId": "urn:parentGroup:001",
  "name": "Temp Network",
  "description": "Network of air temperature sensors deployed across the city",
  "tags": [],
  "observableProperties": [],
  "observedArea": {
    "type": "Polygon",
    "coordinates": [[
      [100.0, 0.0],
      [101.0, 0.0],
      [101.0, 1.0],
      [100.0, 0.0]
    ]]
  },
  "observationTypes": [],
  "@descriptionHistory": "./desc",
  "@featuresOfInterest": "./fois",
  "@observations": "./obs",
  "@dataStreams": "./streams"
}

AbstractProcess

A SML-JSON SimpleProcess, AggregateProcess, PhysicalComponent or PhysicalSystem object

Feature

A GeoJSON Feature object

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [102.0, 0.5]
  },
  "properties": {
    "prop0": "value0"
  }
}

DataStream

{
  "numId": "1",
  "name": "weather",
  "components": {
    "type": "DataRecord",
    ...
  },
  "encodings": [
    "text/csv",
    "application/json"
  ]
}


## Transactions

New resources are created with a POST request on the parent collection, and updated with PATCH.

Resources are deleted with a DELETE request using the ID or a filter on the collection



## Filtering

Follow OData or OpenSearch convention?

#### Spatial Filter

fois?bbox=lat,lon,lat,lon

#### Temporal Filter

streams/weather/historical?time=iso/iso
streams/weather/realtime


## Websocket extension

Websocket connections can be made on `*/streams/{id}/live` URLs with the same filter as regular HTTP connections. (In the core, only HTTP streaming connections are possible on live stream URLs).

The replay extension allows HTTP streaming and websocket connections on `*/streams/{id}/past` URLs to replay data at a particular speed.

Websocket connections are also possible on collections to get notified of additions/deletions.


TODO: think about multiplexing websocket connections


## MQTT extension

MQTT connections can be made by using the URL path (up to the stream id) as the SUBSCRIBE topic (e.g. "org-name/procedures/temp_network/streams/temp"