

openEO API for Subscriptions 0.4.2 documentation

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.

Table of Contents

• Topics
• Schemas

Topics

subscribe 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	Type	Description	Accepted values
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.	Any
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any

Example

{
  "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	Type	Description	Accepted values
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.topics (required)	array(string)		Any

Example

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

subscribe 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	Type	Description	Accepted values
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.	Any
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.topics (required)	array(object)	A list of topics to (un)subscribe to/from.	Any
payload.topics.topic (required)	string		Any

Example

{
  "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"
      }
    ]
  }
}

subscribe openeo.unsubscribe

Message

Unsubscribes from certain topics.

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

Payload

Name	Type	Description	Accepted values
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.	Any
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.topics (required)	array(object)	A list of topics to (un)subscribe to/from.	Any
payload.topics.topic (required)	string		Any

Example

{
  "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	Type	Description	Accepted values
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.job_id (required)	string	Unique identifier of a job that is generated by the back-end during job submission.	Any
payload.output (required)		Output data of any type	Any

Example

{
  "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	Type	Description	Accepted values
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.job_id (required)	string	Unique identifier of a job that is generated by the back-end during job submission.	Any
payload.message (required)	string	The thrown debug message	Any
payload.process	object	Process throwing the debug message.	Any
payload.process.name (required)	string	Name of the process.	Any
payload.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.	Any

Example

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

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	Type	Description	Accepted values
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.job_id (required)	string	Unique identifier of a job that is generated by the back-end during job submission.	Any
payload.status (required)	string	Current status	submitted, queued, running, canceled, finished, error
payload.progress	number	Progress of a running job in percent.	Any

Example

{
  "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	Type	Description	Accepted values
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.user_id (required)	string	Unique identifier of the user.	Any
payload.path (required)	string	Path of the file, relative to the user's root directory. MUST NOT start with a slash and MUST NOT be url-encoded.	Any
payload.action (required)	string	Describes what has changed.	created, updated, deleted

Example

{
  "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	Type	Description	Accepted values
message (required)	object		Any
message.issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
message.topic (required)	string	Message type	Any
payload (required)	object		Any
payload.name (required)	string	Unique identifier for EO datasets.	Any
payload.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.	Any
payload.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.	Any
payload.spatial_extent.crs	oneOf	Coordinate reference system specified as EPSG code or PROJ definition. Defaults to 4326 (EPSG code 4326) unless the client explicitly requests a different coordinate reference system.	Any
payload.spatial_extent.crs.0	integer		Any
payload.spatial_extent.crs.1	string		Any
payload.spatial_extent.west (required)	number	West (lower left corner, coordinate axis 1).	Any
payload.spatial_extent.south (required)	number	South (lower left corner, coordinate axis 2).	Any
payload.spatial_extent.east (required)	number	East (upper right corner, coordinate axis 1).	Any
payload.spatial_extent.north (required)	number	North (upper right corner, coordinate axis 2).	Any
payload.spatial_extent.base	number	Base (optional, lower left corner, coordinate axis 3).	Any
payload.spatial_extent.height	number	Height (optional, upper right corner, coordinate axis 3).	Any

Example of payload (generated)

{
  "message": {
    "issued": "2019-11-27T10:30:45Z",
    "topic": "openeo.sample"
  },
  "payload": {
    "name": "MOD18Q1",
    "temporal_extent": [
      "2016-01-01T02:30:00Z",
      "2016-01-01T04:45:00Z"
    ],
    "spatial_extent": {
      "crs": 7099,
      "west": 0,
      "south": 0,
      "east": 0,
      "north": 0,
      "base": 0,
      "height": 0
    }
  }
}

Schemas

authorization

Name	Type	Description	Accepted values
authorization	string		Any

Example

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

message

Name	Type	Description	Accepted values
issued (required)	string	Date and time when the message was sent, formatted as a RFC 3339 date-time.	Any
topic (required)	string	Message type	Any

Example (generated)

{
  "issued": "2019-11-27T10:30:45Z",
  "topic": "openeo.sample"
}

collection_name

Name	Type	Description	Accepted values
collection_name	string		Any

Example

"MOD18Q1"

job_id

Name	Type	Description	Accepted values
job_id	string		Any

Example

"a3cca2b2aa1e3b5b"

user_id

Name	Type	Description	Accepted values
user_id	string		Any

Example

"john_doe"

topics

Name	Type	Description	Accepted values
topics	array(object)		Any
topics.topic (required)	string		Any

Example

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