diff --git a/docs/source/data-publishing/ogcapi-processes.rst b/docs/source/data-publishing/ogcapi-processes.rst index e62d3ff0c..6cd214c5c 100644 --- a/docs/source/data-publishing/ogcapi-processes.rst +++ b/docs/source/data-publishing/ogcapi-processes.rst @@ -14,15 +14,47 @@ The pygeoapi offers two processes: a default ``hello-world`` process which allow Configuration ------------- +The below configuration is an example of a process defined within the pygeoapi internal plugin registry: + .. code-block:: yaml processes: - - # enabled by default + # enabled by default hello-world: processor: name: HelloWorld +The below configuration is an example of a process defined as part of a custom Python process: + +.. code-block:: yaml + + processes: + # enabled by default + hello-world: + processor: + # refer to a process in the standard PYTHONPATH + # e.g. my_package/my_module/my_file.py (class MyProcess) + # the MyProcess class must subclass from pygeoapi.process.base.BaseProcessor + name: my_package.my_module.my_file.MyProcess + +See :ref:`example-custom-pygeoapi-processing-plugin` for processing plugin examples. + +Processing and response handling +-------------------------------- + +pygeoapi processing plugins must return a tuple of media type and native outputs. Multipart +responses are not supported at this time, and it is up to the process plugin implementor to return a single +payload defining multiple artifacts (or references to them). + +By default (or via the OGC API - Processes ``response: raw`` execution parameter), pygeoapi provides +processing responses in their native encoding and media type, as defined by a given +plugin (which needs to set the response content type and payload accordingly). + +pygeoapi also supports a JSON-based response type (via the OGC API - Processes ``response: document`` +execution parameter). When this mode is requested, the response will always be a JSON encoding, embedding +the resulting payload (part of which may be Base64 encoded for binary data, for example). + + Asynchronous support -------------------- @@ -33,15 +65,27 @@ an asynchronous design pattern. This means that when a job is submitted in asyn mode, the server responds immediately with a reference to the job, which allows the client to periodically poll the server for the processing status of a given job. -pygeoapi provides asynchronous support by providing a 'manager' concept which, well, +In keeping with the OGC API - Processes specification, asynchronous process execution +can be requested by including the ``Prefer: respond-async`` HTTP header in the request. + +Job management is required for asynchronous functionality. + +Job management +-------------- + +pygeoapi provides job management by providing a 'manager' concept which, well, manages job execution. The manager concept is implemented as part of the pygeoapi :ref:`plugins` architecture. pygeoapi provides a default manager implementation based on `TinyDB`_ for simplicity. Custom manager plugins can be developed for more advanced job management capabilities (e.g. Kubernetes, databases, etc.). -In keeping with the OGC API - Processes specification, asynchronous process execution -can be requested by including the ``Prefer: respond-async`` HTTP header in the request +Job managers +------------ + +TinyDB +^^^^^^ +TinyDB is the default job manager for pygeoapi when enabled. .. code-block:: yaml @@ -52,7 +96,8 @@ can be requested by including the ``Prefer: respond-async`` HTTP header in the r output_dir: /tmp/ MongoDB -------- +^^^^^^^ + As an alternative to the default, a manager employing `MongoDB`_ can be used. The connection to a `MongoDB`_ instance must be provided in the configuration. `MongoDB`_ uses ``localhost`` and port ``27017`` by default. Jobs are stored in a collection named @@ -66,9 +111,9 @@ The connection to a `MongoDB`_ instance must be provided in the configuration. connection: mongodb://host:port output_dir: /tmp/ - PostgreSQL ----------- +^^^^^^^^^^ + As another alternative to the default, a manager employing `PostgreSQL`_ can be used. The connection to a `PostgreSQL`_ database must be provided in the configuration. `PostgreSQL`_ uses ``localhost`` and port ``5432`` by default. Jobs are stored in a table named ``jobs``. diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index 76248fbcb..cadf93a73 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -273,6 +273,8 @@ implementation. Each base class documents the functions, arguments and return types required for implementation. +.. _example-custom-pygeoapi-processing-plugin: + Example: custom pygeoapi processing plugin ------------------------------------------ diff --git a/pygeoapi/api/processes.py b/pygeoapi/api/processes.py index 236f16e16..d547a984e 100644 --- a/pygeoapi/api/processes.py +++ b/pygeoapi/api/processes.py @@ -379,6 +379,8 @@ def execute_process(api: API, request: APIRequest, requested_outputs = data.get('outputs') LOGGER.debug(f'outputs: {requested_outputs}') + response_requested = data.get('response', 'raw') + subscriber = None subscriber_dict = data.get('subscriber') if subscriber_dict: @@ -420,7 +422,7 @@ def execute_process(api: API, request: APIRequest, if status == JobStatus.failed: response = outputs - if data.get('response', 'raw') == 'raw': + if response_requested == 'raw': headers['Content-Type'] = mime_type response = outputs elif status not in (JobStatus.failed, JobStatus.accepted): @@ -433,7 +435,7 @@ def execute_process(api: API, request: APIRequest, else: http_status = HTTPStatus.OK - if mime_type == 'application/json': + if mime_type == 'application/json' or response_requested == 'document': response2 = to_json(response, api.pretty_print) else: response2 = response