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
	/controlStreams	DataStream[] as SWE-JSON
	/controlStreams/{id}	DataStream as SWE-JSON
	/controlStreams/{id}/live	POST SWE Record as json
	/tasks	Task[]	time
	/tasks/{id}	Task
	/tasks/{id}/status	TaskStatus
/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"
  ]
}

Task

{
  "numId": "1",
  "statusReport": {
    "estimatedToC": "2017-04-23T12:23:12Z",
    "lastEvent": "",
    "percentCompletion": "50",
    "procedure": "urn:sensor:0001",
    "requestStatus": "ACCEPTED",
    "statusMessage": "no problem so far",
    "taskStatus": "IN-PROGRESS",
    "updateTime": "2017-04-22T12:00:00Z",
    "taskingParameters": {
      "pan": 12.5,
      "tilt": -15.6 
    }
  }
}

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 */dataStreams/{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 can also be used for tasking by connecting to */controlStreams/{id}/live URLs with an authorized task/session ID. Websocket allows for text/csv and binary encoded tasking messages.

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"