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

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	Type	Format	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"
  }
}

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	Type	Format	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"
    ]
  }
}

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	Type	Format	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"
      }
    ]
  }
}

Message

Unsubscribes from certain topics.

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

Payload

Name	Type	Format	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"
      }
    ]
  }
}

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	Type	Format	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!"
  }
}

Message

Debugging information from job execution.

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

Payload

Name	Type	Format	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
      }
    }
  }
}

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	Type	Format	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
  }
}

Message

Inform about changes regarding the user files.

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

Payload

Name	Type	Format	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"
  }
}

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	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-11-12T09:56:17Z",
  "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"
  }
]

openEO API for Subscriptions

Introduction

Topics

Messages

Schemas

openEO API for Subscriptions 0.3.0

Topics

Subscribe openeo.authorize

Message

Payload

Example

Example of payload (generated)

Publish openeo.welcome

Message

Payload

Example

Example of payload (generated)

Subscribe openeo.subscribe

Message

Payload

Example

Example of payload (generated)

Subscribe openeo.unsubscribe

Message

Payload

Example

Example of payload (generated)

Publish openeo.jobs.output

Message

Payload

Example

Example of payload (generated)

Publish openeo.jobs.debug

Message

Payload

Example

Example of payload (generated)

Publish openeo.jobs.status

Message

Payload

Example

Example of payload (generated)

Publish openeo.files

Message

Payload

Example

Example of payload (generated)

Publish openeo.data

Message

Payload

Example

Messages

Schemas

authorization

Example

message

Example (generated)

collection_name

Example

job_id

Example

user_id

Example

topics

Example