openEO API for Subscriptions 0.3.0

The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.

This is a subset of the openEO API that handles WebSocket-based protocols for subscriptions and notifications.

openeo.authorize, openeo.welcome, openeo.subscribe and openeo.unsubsribe MUST be implemeneted by all back-ends.

Security considerations: A handshake has to be performed directly after establishing the WebSocket connection. The client MUST send a openeo.authorize request and receives a openeo.welcome message after a successful authorization. The WebSocket connections MUST be closed by servers once a request with invalid authorization credentials is sent. Servers are allowed to close connections to clients that have not sent a openeo.authorize request 30 seconds after establishing a WebSocket connection.

Topics

openeo.authorize

Message

Starts a handshake with the server to authorize the client.

The client MUST send a openeo.authorize request directly after establishing the WebSocket connection and a openeo.welcome will be sent by the server after successful authorization. The WebSocket connections MUST be closed if invalid authorization credentials are sent.

Payload

Name Title Type Format Default Description
authorization (Required) string Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually `Bearer`), a space and the actual token for authorization.
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type

Example

Example of payload (generated)

{
  "authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0",
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.authorize"
  }
}

Publish openeo.welcome

Message

Welcome message for clients.

Sends the supported topics, excluding openeo.authorize, openeo.subscribe, openeo.unsubscribe and openeo.welcome (because these MUST be implemented by every back-end anyway). This message MUST be sent by all servers directly after receiving the openeo.authorize message with valid credentials.

Payload

Name Title Type Format Default Description
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
topics (Required) array (string)

Example

Example of payload (generated)

{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.welcome"
  },
  "payload": {
    "topics": [
      "openeo.jobs.output",
      "openeo.jobs.status",
      "openeo.data"
    ]
  }
}

openeo.subscribe

Message

Subscribes to certain topics.

Additional parameters that may be used to restrict the scope of the subscription are described in the specific messages. For example, a restriction of a subscription to a specific job.

The WebSocket connections MUST be closed if invalid authorization credentials are sent.

Payload

Name Title Type Format Default Description
authorization (Required) string Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually `Bearer`), a space and the actual token for authorization.
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
topics (Required) array (object) A list of topics to (un)subscribe to/from.
topic (Required) string One of the supported publish topics.

Example

Example of payload (generated)

{
  "authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0",
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.subscribe"
  },
  "payload": {
    "topics": [
      {
        "topic": "openeo.jobs.status",
        "job_id": "a3cca2b2aa1e3b5b"
      },
      {
        "topic": "openeo.files"
      }
    ]
  }
}

openeo.unsubscribe

Message

Unsubscribes from certain topics.

The WebSocket connections MUST be closed if invalid authorization credentials are sent.

Payload

Name Title Type Format Default Description
authorization (Required) string Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually `Bearer`), a space and the actual token for authorization.
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
topics (Required) array (object) A list of topics to (un)subscribe to/from.
topic (Required) string One of the supported publish topics.

Example

Example of payload (generated)

{
  "authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0",
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.unsubscribe"
  },
  "payload": {
    "topics": [
      {
        "topic": "openeo.jobs.status",
        "job_id": "a3cca2b2aa1e3b5b"
      },
      {
        "topic": "openeo.files"
      }
    ]
  }
}

Publish openeo.jobs.output

Message

Data written to the output console with processes of a job.

Subscriptions to this message can be restricted to a certain job by specifying a job_id.

Payload

Name Title Type Format Default Description
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
job_id (Required) string Unique identifier of a job that is generated by the back-end during job submission.
output (Required) Output data of any type

Example

Example of payload (generated)

{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.jobs.debug"
  },
  "payload": {
    "job_id": "a3cca2b2aa1e3b5b",
    "output": "Hello world!"
  }
}

Publish openeo.jobs.debug

Message

Debugging information from job execution.

Subscriptions to this message can be restricted to a certain job by specifying a job_id.

Payload

Name Title Type Format Default Description
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
job_id (Required) string Unique identifier of a job that is generated by the back-end during job submission.
message (Required) string The thrown debug message
process object Process throwing the debug message.
name (Required) string Name of the process.
parameters (Required) object Key-value pairs for the parameters of the process. The keys are the parameter names and the values are the actual values specified for the parameter. Specify the empty object if the process does not have any parameters or was called without parameters.

Example

Example of payload (generated)

{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.jobs.debug"
  },
  "payload": {
    "job_id": "a3cca2b2aa1e3b5b",
    "message": "Invalid SRS specified, defaulting to EPSG:4326.",
    "process": {
      "name": "filter_bbox",
      "parameters": {
        "srs": "EPSG:9999",
        "west": 55,
        "east": 56,
        "north": 11,
        "south": 10
      }
    }
  }
}

Publish openeo.jobs.status

Message

Inform about a status change of a job.

Subscriptions to this message can be restricted to a certain job by specifying a job_id.

Payload

Name Title Type Format Default Description
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
job_id (Required) string Unique identifier of a job that is generated by the back-end during job submission.
status (Required) string Current status
progress number Progress of a running job in percent.

Example

Example of payload (generated)

{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.jobs.status"
  },
  "payload": {
    "job_id": "a3cca2b2aa1e3b5b",
    "status": "running",
    "progress": 75.5
  }
}

Publish openeo.files

Message

Inform about changes regarding the user files.

Subscriptions to this message can't be restricted to a certain file or folder.

Payload

Name Title Type Format Default Description
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
user_id (Required) string Unique identifier of the user.
path (Required) string Path of the file, relative to the user's root dir, i.e. MUST NOT contain the name of that root dir and MUST NOT start with a slash. MUST NOT be url-encoded.
action (Required) string Describes what has changed.

Example

Example of payload (generated)

{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.files"
  },
  "payload": {
    "user_id": "john_doe",
    "path": "new_file.txt",
    "action": "created"
  }
}

Publish openeo.data

Message

Inform about changes regarding an EO dataset.

At least one of the temporal_extent and spatial_extent fields MUST be specified.

Subscriptions to this message can be restricted to a certain collection by specifying name and providing a valid collection name.

Payload

Name Title Type Format Default Description
message (Required) object
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type
payload (Required) object
name (Required) string Unique identifier for EO datasets.
temporal_extent array (string) MUST be specified if the temporal extent of the dataset has changed. The temporal extent is always specified as an array, that consists of either a single timestamp or a start and an end time, each element formatted as a RFC 3339 date-time. Specifies the temporal extent of the data that has changed, not of the whole dataset. Example: The dataset covers images from beginning of 2015 until the end of 2018. A single image has been added, captured at the first day in 2019 at 01:00:00 UTC (1am). The spatial extent specified here must be an array containing a single string: `2019-01-01T01:00:00Z`.
spatial_extent object MUST always be specified. It is the spatial extent of the data that was changed. Specifies the spatial extent of the data that has changed, not of the whole dataset. Example: The dataset covers the whole world and an image of Austria has been added. The spatial extent specified here must be the bounding box of Austria.
crs string EPSG:4326 Coordinate reference system. EPSG codes must be supported. In addition, proj4 strings should be supported by back-ends. Whenever possible, it is recommended to use EPSG codes instead of proj4 strings. Defaults to `EPSG:4326` unless the client explicitly requests a different coordinate reference system.
west (Required) number Lower left corner, coordinate axis 1 (west).
east (Required) number Upper right corner, coordinate axis 1 (east).
north (Required) number Lower left corner, coordinate axis 2 (north).
south (Required) number Upper right corner, coordinate axis 2 (south).
base number Lower left corner, coordinate axis 3 (base, optional).
height number Upper right corner, coordinate axis 3 (height, optional).

Example

{
  "message": {
    "issued": "2018-08-07T14:06:36Z",
    "topic": "openeo.data"
  },
  "payload": {
    "name": "MOD18Q1",
    "temporal_extent": [
      "2018-08-07T15:30:00Z",
      "2018-08-08T16:43:00Z"
    ],
    "spatial_extent": {
      "west": 34.6,
      "east": 35.1,
      "south": 39.6,
      "north": 40.1
    }
  }
}

Messages

Schemas

authorization

Name Title Type Format Default Description
authorization string Takes the same values as the HTTP Authorization header that is accepted by most openEO endpoints. The value is concatenated from the Authorization scheme (usually `Bearer`), a space and the actual token for authorization.

Example

"Bearer eyJhbGciOiJIUzI1NiJ9.e30.4E_Bsx-pJi3kOW9wVXN8CgbATwP09D9V5gxh9-9zSZ0"

message

Name Title Type Format Default Description
issued (Required) string date-time Date and time when the message was sent, formatted as a RFC 3339 date-time.
topic (Required) string Message type

Example (generated)

{
  "issued": "2018-10-12T15:09:51Z",
  "topic": "openeo.sample"
}

collection_name

Name Title Type Format Default Description
collection_name string Unique identifier for EO datasets.

Example

"MOD18Q1"

job_id

Name Title Type Format Default Description
job_id string Unique identifier of a job that is generated by the back-end during job submission.

Example

"a3cca2b2aa1e3b5b"

user_id

Name Title Type Format Default Description
user_id string Unique identifier of the user.

Example

"john_doe"

topics

Name Title Type Format Default Description
topics array (object) A list of topics to (un)subscribe to/from.
topic (Required) string One of the supported publish topics.

Example

[
  {
    "topic": "openeo.jobs.output",
    "job_id": 123
  },
  {
    "topic": "openeo.jobs.status"
  },
  {
    "topic": "openeo.data",
    "name": "MOD18Q1"
  }
]