Merge pull request #126 from geopython/ogcapi-processes

add exercise for OGC API - Processes (#125)

workshop/content/docs/advanced/bridges.md

@@ -1,10 +1,10 @@
 ---
-title: Exercise 8 - pygeoapi as a Bridge to Other Services
+title: Exercise 8 - pygeoapi as a bridge to other services
 ---
 
-# Exercise 8 - pygeoapi as a Bridge to Other Services
+# Exercise 8 - pygeoapi as a bridge to other services
 
-In this section we explore how pygeoapi can be used as a facade, or a bridge, to re-publish web services with different interfaces. These bridges can help [organisations migrating from OWS to OGC API](https://ogcapi-workshop.ogc.org/transition-and-migration/).
+In this section we explore how pygeoapi can be used as a facade, or a bridge, to re-publish web services with different interfaces. These bridges can help [organisations migrating from OWS to OGC API](https://ogcapi-workshop.ogc.org/transition-and-migration).
 
 ## Publishing WFS as OGC API - Features
 
@@ -64,7 +64,7 @@ a wider audience. Let's set up an API on top of an existing WFS hosted by the ci
               layer: territorio:suol_epicentri_storici
     ```
 
-Save the file and restart Docker Compose. Navigate to `http://localhost:5000/collections` 
+Save the file and restart Docker Compose. Navigate to <http://localhost:5000/collections>
 to evaluate whether the new dataset has been published.
 
 Note these important configuration slices under `providers`:
@@ -136,9 +136,9 @@ We can use the pygeoapi's WMSFacade provider to publish OGC Web Map Service (WMS
 
 Run the following requests in your web browser:
 
-- default map: [http://localhost:5000/collections/wms-facade-demo/map?f=png](http://localhost:5000/collections/wms-facade-demo/map?f=png)
-- specific width/height: [http://localhost:5000/collections/wms-facade-demo/map?f=png&width=800&height=600](http://localhost:5000/collections/wms-facade-demo/map?f=png&width=800&height=600)
-- specific area of interest (bbox of Canada): [http://localhost:5000/collections/wms-facade-demo/map?f=png&width=800&height=600](http://localhost:5000/collections/wms-facade-demo/map?f=png&bbox=-142,42,-52,84)
+- default map: <http://localhost:5000/collections/wms-facade-demo/map?f=png>
+- specific width/height: <http://localhost:5000/collections/wms-facade-demo/map?f=png&width=800&height=600>
+- specific area of interest (bbox of Canada): <http://localhost:5000/collections/wms-facade-demo/map?f=png&width=800&height=600&bbox=-142,42,-52,84>
 
 ![](../assets/images/maps-response.png){ width=80% }
 
@@ -148,7 +148,7 @@ Run the following requests in your web browser:
 
 ## Publishing CSW as OGC API - Records
 
-In this section we'll have a look at how to publish Catalogue Services for the Web (CSW) as OGC API - Records. For that, we will use the [pycsw OGC CITE demo](https://demo.pycsw.org/cite/) CSW service.
+In this section we'll have a look at how to publish Catalogue Service for the Web (CSW) as OGC API - Records. For that, we will use the [pycsw OGC CITE demo](https://demo.pycsw.org/cite/) CSW service.
 
 !!! question "Update the pygeoapi configuration"
 
@@ -225,4 +225,4 @@ In this section we'll have a look at how to Publish a SensorThings API `Thing` a
                 name: SensorThings
                 data: https://toronto-bike-snapshot.sensorup.com/v1.0/
                 entity: Things
-    ```
+    ```

workshop/content/docs/advanced/crs.md

@@ -101,11 +101,11 @@ We can even do this in the Swagger UI, but using the browser is quite fast and c
 !!! question "Collection Metadata"
 
     Open the URL: 
-    [http://localhost:5000/collections/firenze-terrains-vec](http://localhost:5000/collections/firenze-terrains-vec)
+    <http://localhost:5000/collections/firenze-terrains-vec>
     Your configured CRSs are displayed at the bottom of the page: "Reference Systems" and "Storage CRS".
 
     See these in JSON format, also at the bottom: 
-    http://localhost:5000/collections/firenze-terrains-vec?f=json
+    <http://localhost:5000/collections/firenze-terrains-vec?f=json>
     ```yaml
        .
        .
@@ -124,7 +124,7 @@ We can even do this in the Swagger UI, but using the browser is quite fast and c
 !!! question "Using the CRS query parameter"
 
     Open the URL: 
-    [http://localhost:5000/collections/firenze-terrains-vec/items?f=json&crs=http://www.opengis.net/def/crs/EPSG/0/4258](http://localhost:5000/collections/firenze-terrains-vec/items?f=json&crs=http://www.opengis.net/def/crs/EPSG/0/4258)
+    <http://localhost:5000/collections/firenze-terrains-vec/items?f=json&crs=http://www.opengis.net/def/crs/EPSG/0/4258>
 
     This is ETRS89, similar to WGS84, but for the European Continent (Datum) and in lat,lon order. This is e.g. used in INSPIRE.
 

workshop/content/docs/publishing/first.md

@@ -38,7 +38,7 @@ To test:
     docker-compose up
     ```
     </div>
-    1. Open `http://localhost:5000` in your browser, verify some collections
+    1. Open <http://localhost:5000> in your browser, verify some collections
     1. Close by typing `CTRL-C`
 
 !!! note
@@ -145,7 +145,7 @@ we have also mounted (made available) the entire local directory `./data`.
 
     1. Start by typing `docker-compose up` 
     1. Observe logging output
-    1. If no errors: open http://localhost:5000
+    1. If no errors: open <http://localhost:5000>
     1. Look for the Point of interest collection
     1. Browse through the items of the collection
     1. Check the json representation by adding ?f=json to url (or click 'json' in top right)

workshop/content/docs/publishing/index.md

@@ -6,7 +6,7 @@ title: Publishing data
 
 !!! note
 
-    Ensure that you have pygeoapi setup and can navigate the default configuration and service (`http://localhost:5000`).
+    Ensure that you have pygeoapi setup and can navigate the default configuration and service running at <http://localhost:5000>.
 
 In this section, you will learn how to publish different types of geospatial data and metadata
 through the following exercises:
@@ -17,4 +17,6 @@ through the following exercises:
 - [Exercise 4 - Tiles of geospatial data via OGC API - Tiles](ogcapi-tiles.md)
 - [Exercise 5 - Maps of geospatial data via OGC API - Maps](ogcapi-maps.md)
 - [Exercise 6 - Metadata via OGC API - Records](ogcapi-records.md)
-- [Exercise 7 - Environmental data via OGC - Environmental Data Retrieval](ogcapi-edr.md)
+- [Exercise 7 - Environmental data via OGC API - Environmental Data Retrieval](ogcapi-edr.md)
+- [Exercise 8 - Functions via OGC API - Processes](ogcapi-processes.md)
+- [Exercise 9 - Functions via OGC API - Processes](ogcapi-processes.md)

workshop/content/docs/publishing/ogcapi-coverages.md

@@ -70,7 +70,7 @@ You can now add `53_ED1_G.tif` to pygeoapi:
 
     The rasterio provider `format.name` directive **requires** a valid [GDAL raster driver short name](https://gdal.org/drivers/raster/index.html)
 
-Save the configuration and restart Docker Compose. Navigate to `http://localhost:5000/collections` to evaluate whether the new dataset has been published.
+Save the configuration and restart Docker Compose. Navigate to <http://localhost:5000/collections> to evaluate whether the new dataset has been published.
 
 ## Client access
 

workshop/content/docs/publishing/ogcapi-edr.md

@@ -1,8 +1,8 @@
 ---
-title: Exercise 7 - Environmental data via OGC - Environmental Data Retrieval
+title: Exercise 7 - Environmental data via OGC API - Environmental Data Retrieval
 ---
 
-# Exercise 7 - Environmental data via OGC - Environmental Data Retrieval
+# Exercise 7 - Environmental data via OGC API - Environmental Data Retrieval
 
 [OGC API - Environmental Data Retrieval](https://ogcapi.ogc.org/edr) provides a Web API to access
 environmental data using well defined query patterns:
@@ -63,7 +63,7 @@ Let's try publishing some ICOADS data via the EDR xarray plugin. The sample ICOA
                   mimetype: application/x-netcdf
 ```
 
-Save the configuration and restart Docker Compose. Navigate to `http://localhost:5000/collections` to evaluate whether the new dataset has been published.
+Save the configuration and restart Docker Compose. Navigate to <http://localhost:5000/collections> to evaluate whether the new dataset has been published.
 
 At first glance, the `icoads-sst` collection appears as a normal OGC API - Coverages collection. Let's look a bit closer at the colleciton description:
 

workshop/content/docs/publishing/ogcapi-features.md

@@ -76,7 +76,7 @@ Let's add the file `workshop/exercises/data/osm_places_kosovo.gpkg`:
               table: gis_osm_places_free_1 # table name within gpkg
     ```
 
-Save the file and restart Docker Compose. Navigate to `http://localhost:5000/collections` to evaluate whether the new dataset with
+Save the file and restart Docker Compose. Navigate to <http://localhost:5000/collections> to evaluate whether the new dataset with
 title *"Places in Kosovo 2023"* has been published.
 
 !!! note

workshop/content/docs/publishing/ogcapi-processes.md

@@ -0,0 +1,70 @@
+---
+title: Exercise 8 - Functions via OGC API - Processes
+---
+
+# Exercise 8 - Functions via OGC API - Processes
+
+[OGC API - Processes](https://ogcapi.ogc.org/processes) supports the wrapping of computational tasks into
+executable processes that can be offered by a server through a Web API and be invoked by a client application.
+
+* [OGC API - Processes: Part 1: Core](https://docs.ogc.org/is/18-062r2/18-062r2.html)
+
+OGC API - Processes uses OGC API - Common as a building block, thus enabling streamlined deployment and integration
+for clients and users.
+
+## pygeoapi support
+
+pygeoapi supports the OGC API - Processes specification, with the ability to publish Python code (no matter how
+simple or complex) as an OGC API Process definition.  pygeoapi also support synchronous or asynchronous processing,
+with the ability to store and retrive the status/results of 'jobs'.
+
+!!! note
+
+    See [the official documentation](https://docs.pygeoapi.io/en/latest/data-publishing/ogcapi-processes.html) for more information
+    on publishing processes in pygeoapi
+
+
+## Publishing Python code as a process in pygeoapi
+
+With pygeoapi we can setup OGC API - Processes using Python code that implements the pygeoapi `BaseProcessor`, which is a core pygeoapi
+abstract base class.  In this exercise we will implemented a "squared" function as a process using the sample Python code in
+`workshop/exercises/plugins/process/squared.py`.  The process is already defined to be part of the pygeoapi environment and configuration.
+
+!!! question "Update the pygeoapi configuration"
+
+    Open the pygeoapi configuration file in a text editor. Add a new process section as follows:
+
+``` {.yaml linenums="1"}
+    squared:
+        type: process
+        processor:
+            name: pygeoapi.process.squared.SquaredProcessor
+```
+
+!!! question "Update Python code"
+
+    Open the Python code at `workshop/exercises/plugins/process/squared.py`.  Find the `execute` function and update the Python
+    code to calculate the input value squared.
+
+
+Save the configuration and restart Docker Compose. Navigate to <http://localhost:5000/processes> to evaluate whether the new process has
+been published.  Inspect the detailed process metadata by navigating to <http://localhost:5000/processes/squared> to inspect how the process
+metadata defined in the Python code/file is made available in JSON..
+
+## Client access
+
+### Swagger
+
+The easiest way to test the new process is by using pygeoapi's built in Swagger interface.  Navigate to <http://localhost:5000/openapi> and try out
+the process in the Swagger UI.
+
+![Squared function process execution](../assets/images/oaproc-squared-1.png){ width=120% }
+
+![Squared function process execution](../assets/images/oaproc-squared-2.png){ width=120% }
+
+![Squared function process execution](../assets/images/oaproc-squared-3.png){ width=120% }
+
+
+# Summary
+
+Congratulations!  You are now able to publish Python code as a process to pygeoapi.

workshop/content/docs/publishing/ogcapi-records.md

@@ -59,7 +59,7 @@ Catalogue backend. We will use the sample catalogue in `workshop/exercises/data/
               title_field: title
 ```
 
-Save the configuration and restart Docker Compose. Navigate to `http://localhost:5000/collections` to evaluate whether the new dataset has been published.
+Save the configuration and restart Docker Compose. Navigate to <http://localhost:5000/collections> to evaluate whether the new dataset has been published.
 
 ## Metadata formats
 

workshop/content/docs/publishing/ogcapi-tiles.md

@@ -98,12 +98,12 @@ tippecanoe --output-to-directory=/data/tiles/ --force --maximum-zoom=16 --drop-d
                     mimetype: application/vnd.mapbox-vector-tile
 ```
 
-Save the file and restart Docker Compose. Navigate to `http://localhost:5000/collections` to evaluate whether the new dataset has been published.
+Save the file and restart Docker Compose. Navigate to <http://localhost:5000/collections> to evaluate whether the new dataset has been published.
 
 Additional check for the following tile specific endpoints in the `Hyderabad` collection:
 
-- tile links in [http://localhost:5000/collections/hyderabad/tiles](http://localhost:5000/collections/hyderabad/tiles)
-- tile metadata in [http://localhost:5000/collections/hyderabad/tiles/WorldCRS84Quad/metadata](http://localhost:5000/collections/hyderabad/tiles/WorldCRS84Quad/metadata)
+- tile links in <http://localhost:5000/collections/hyderabad/tiles>
+- tile metadata in <http://localhost:5000/collections/hyderabad/tiles/WorldCRS84Quad/metadata>
 
 ![TileSet](../assets/images/vtiles-hyderabad.png)
 
@@ -188,9 +188,9 @@ QGIS supports OGC API Vector Tiles via the [Vector Tiles Layer](https://docs.qgi
 
     Before entering QGIS, access your pygeoapi installation page on the browser and follow these steps.
 
-    - access the collection page of the tiles dataset: `http://localhost:5000/collections/Hyderabad`
-    - navigate to the tiles page by clicking on `tiles`: `http://localhost:5000/collections/Hyderabad/tiles`
-    - click in `Tiles metadata in tilejson format`: `http://localhost:5000/collections/Cycle/Hyderabad/WorldCRS84Quad/metadata`
+    - access the collection page of the tiles dataset: <http://localhost:5000/collections/Hyderabad>
+    - navigate to the tiles page by clicking on `tiles`: <http://localhost:5000/collections/Hyderabad/tiles>
+    - click in `Tiles metadata in tilejson format`: `http://localhost:5000/collections/Cycle/Hyderabad/WorldCRS84Quad/metadata>
     - note the URL in `tiles`: `http://localhost:5000/collections/Hyderabad/tiles/WorldCRS84Quad/{tileMatrix}/{tileRow}/{tileCol}?f=mvt` and of the values of minZoom and maxZoom
 
     Follow these steps to connect to a service and access vector tiles:

workshop/content/docs/setup.md

@@ -150,7 +150,7 @@ data is a one-liner.
     </div>
 
 
-That's all! Open your browser and navigate to `http://localhost:5000`, the pygeoapi page will display.
+That's all! Open your browser and navigate to <http://localhost:5000>, the pygeoapi page will display.
 As part of the initial `docker run`, Docker will download the pygeoapi Docker Image from [Docker hub](https://hub.Docker.com/r/geopython/pygeoapi).
 This may take some time, as the Docker image includes all dependencies (such as GDAL, etc.). Be patient! This is a one-time download for the entire workshop, or
 you may want to do this beforehand. 
@@ -200,7 +200,7 @@ within the container by a local file which you can edit in your favourite text e
     ```
     </div>
 
-    At this point, navigate to `http://localhost:5000` to verify the new title and description.
+    At this point, navigate to <http://localhost:5000> to verify the new title and description.
 
 
 By using a Docker volume mount (`-v` option), Docker attaches or 'mounts' a

workshop/content/mkdocs.yml

@@ -17,7 +17,8 @@ nav:
         - Exercise 4 - Tiles of geospatial data via OGC API - Tiles: publishing/ogcapi-tiles.md
         - Exercise 5 - Maps of geospatial data via OGC API - Maps: publishing/ogcapi-maps.md
         - Exercise 6 - Metadata via OGC API - Records: publishing/ogcapi-records.md
-        - Exercise 7 - Environmental data via OGC - Environmental Data Retrieval: publishing/ogcapi-edr.md
+        - Exercise 7 - Environmental data via OGC API - Environmental Data Retrieval: publishing/ogcapi-edr.md
+        - Exercise 8 - Functions via OGC API - Processes: publishing/ogcapi-processes.md
     - Advanced topics:
         - advanced/index.md
         - Multilingual support: advanced/i18n.md
@@ -29,7 +30,7 @@ nav:
         - Semantic Web and Linked Data: advanced/semantic-web-linked-data.md
         - Cloud deployment: advanced/cloud.md
         - INSPIRE support: advanced/inspire.md
-        - Exercise 8 - pygeoapi as a Bridge to Other Services: advanced/bridges.md
+        - Exercise 9 - pygeoapi as a bridge to other services: advanced/bridges.md
     - Conclusion: conclusion.md
 
 use_directory_urls: true

workshop/exercises/README.md

@@ -9,7 +9,7 @@ To start Docker Compose, from `workshop/exercises`, run the following command:
 docker-compose up -d
 ```
 
-This will start a Docker container with pygeoapi (reachable from the browser at [this address](http://localhost:5000/)).
+This will start a Docker container with pygeoapi (reachable from the browser at <http://localhost:5000/>).
 
 To stop, use the command:
 

workshop/exercises/docker-compose.yml

@@ -45,3 +45,4 @@ services:
     volumes:
       - ./pygeoapi.config.yml:/pygeoapi/local.config.yml
 #      - ./data:/data # Exercise 1 - First - Ready to pull data from here
+      - ./plugins/process/squared.py:/pygeoapi/pygeoapi/process/squared.py  # Exercise 8