Demystifying OGC APIs with GeoServer: introduction and status of implementation - FOSS4G 2023

The OGC APIs are a fresh take at doing geo-spatial APIs, based on WEB API concepts and modern formats, including:

- Small core with basic functionality, extra functionality provided by extensions
- OpenAPI/RESTful based<
- JSON first, while still allowing to provide data in other formats
- No mandate to publish schemas for data
- Improved support for data tiles (e.g., vector tiles)
- Specialized APIs in addition to general ones (e.g., DAPA vs OGC API - Processes)
- Full blown services, building blocks, and ease of extensibility

This presentation will provide an introduction to various OGC APIs and extensions, such as Features, Styles, Maps and Tiles, STAC and CQL2 filtering.

Some have reached a final release, some are in draft: we will discuss their trajectory towards official status, as well as how good the GeoServer implementation is tracking them, and show examples based on the GeoServer HTML representation of the various resources.

Transcript

1. Demystifying OGC APIs with GeoServer: introduction and status of implementation Ing. Andrea Aime GeoSolutions 1
2. GeoSolutions Enterprise Support Services Deployment Subscription Professional Training Customized Solutions GeoNode • Offices in Italy & US, Global Clients/Team • 30+ collaborators, 25+ Engineers • Our products • Our Offer 2
3. Affiliations We strongly support Open Source, it Is in our core We actively participate in OGC working groups and get funded to advance new open standards We support standards critical to GEOINT 3
4. OGC API - Common elements 4
5. OGC APIs - OpenAPI • Fresh take on spatial data interoperability • Based on OpenAPI/RESTful concepts • Resource/representation • HTTP verbs • Small core, a basic service can be implemented in a matter of days • Extensions for every other functionality 5
6. OGC API (OAPI) Common • Can be found at: https://github.com/opengeospatial/oapi_common • Resources: • / (landing page) • /conformance (conformance classes implemented) • For services exposing data: • /collections • /collection/{collectionId} • OpenAPI definition linked from landing page with rel service-desc 6
7. Links, links everywhere! • All resources are linked to the others, in the various encodings: /collections /collections/{collectionId} Backlinks to self and alternative representations (different formats/encodings) Links to each collection in each of its formats { "href":"http://data.example.org/collections.json", "rel":"self", "type":"application/json", "title":"this document" } 7
8. Resource representations • OAPI Commons recommends: ◦ HTML for humans and crawlers ◦ JSON for machine to machine • Choose: ◦ Accept header ◦ Custom query param (“f” is a common choice) 8
9. Extensions and conformance • Tiny core, bare minimum for a working service • Modular extensions for everything else • Find what is supported using conformance declaration 9
10. GeoServer implementation, common bits 10
11. One service per API • The current GeoServer implementation has one separate service per API • Matches 1-1 classic OGC services • Each OGC API is built on top of the classic OGC service engine (found in GeoServer core) • An implementation of a uber-service with all blocks together is possible, but not trivial, since each service is a pluggable module in GeoServer (can be pulled away at any time) OGC API - Features WFS 1.1 Features services engine WFS 1.0 WFS 2.0 11
12. Mimic classic OGC service • Same output formats as classic OGC service ◦ e.g., can extract zipped shapefile out of OGC API - Features • Similar vendor extensions ◦ e.g. can filter using Extended CQL ◦ but some vendor extensions are not yet exposed (e.g., filtering mosaic images via CQL like in WCS) • Integrate same basic functionality ◦ Authentication and authorization supported out of the box ◦ Monitoring and control-flow similarly supported 12
13. HTML Resource representations • HTML representation is controlled by templates, fully user customizable • Example, collections page, vanilla: 13
14. Customizable links • Configurable links for services and collections • Examples: license, metadata, enclosure, INSPIRE tags, human readable description of the data set or collection 14
15. OGC API - Features 15
16. Features API Core • In addition to OAPI core: • /collection/{collectionId}/items • /collection/{collectionId}/items/{itemId} • Only supported CRS are • CRS84 (WGS84 lon/lat) • CRS84h (WGS84 lon/lat/height) • Schema not required, features can be anything: • Simple • Complex • Heterogeneous • “describeBy” can link to schema (optional) 16
17. OpenAPI definition 17
18. /collection/{collectionId}/items • Lists the contents of a collection • Can be a GeoJSON document, GML, anything • Filtering • bbox in CRS84 or CRS84h • datetime (instant or range of times) • extra parameters declared in the API document (only by equality, not supported by GS) …/collections/buildings/items? bbox=41,54,42,55 &datetime=2018-02-12T23%3A20%3A52Z &buildingState=good 18
19. Paging • limit query parameter (first page) • A limit is always present (server default) • Paging works through links, "prev" and "next" rel values [ { "href":"http://example.org/collections/buildings/items.json?limit:50", "rel":"prev", "type":"application/geo+json" }, { "href":"http://example.org/collections/buildings/items.json?limit:50&offset:50", "rel":"self", "type":"application/geo+json" }, { "href":"http://example.org/collections/buildings/items.json?limit:50&offset:100", "rel":"next", "type":"application/geo+json" } ] 19
20. CITE compliance • GeoServer 2.24.x nightly builds are passing OGC API - Features compliance tests 20
21. Part 2 - CRS by Reference • OGC API - Features, part 2, Coordinate Reference Systems by Reference • Info about storage CRS • BBOX with CRS • Output reprojection • CRS information as a response header (does not rely on format native ability) • Compliant, CITE tests pass { "crs": [ "http://www.opengis.net/def/crs/OGC/1.3/CRS84", "http://www.opengis.net/def/crs/EPSG/0/4326", "http://www.opengis.net/def/crs/EPSG/0/3857" ], "storageCrs": "http://www.opengis.net/def/crs/EPSG/0/26713" } 21
22. Part 3 - Filtering (draft) • Queryables: properties that can be used for filtering ◦ May be a sub-set of the actual attributes ◦ May not even match the attributes (e..g, like “anyText” in CSW) • filter: the filter specification • filter-lang: the language used • filter-crs: the CRS for the geometries used in the filter • cql2-text, cql2-json • GeoServer supports also ecql-text (classic GeoServer extended CQL) 22
23. CQL2 encodings (earlier draft) eo:cloud_cover BETWEEN 0.1 AND 0.2 AND landsat:wrs_row=28 AND landsat:wrs_path=203 { "and": [ { "between": [ {"property": "eo:cloud_cover"}, 0.1, 0.2 ] }, { "=": [{"property": "landsat:wrs_row"},28] }, { "=": [{"property": "landsat:wrs_path"},203] } ] } &filter-lang=cql2-text &filter-lang=cql2-json 23
24. Sorting • Not part of OGC API - Features • Discussed in issue 157 • Syntax borrowed from OGC API - Records /items?sortby=name,-dateOfBirth 24
25. STAC API 25
26. STAC API (RC1) • Spatio Temporal Asset Catalog • Search engine for “assets” in space and time • Typical asset: satellite imagery • GS implementation, compatible with OGC API - Features 26
27. GeoServer implementation structure Collection Item Granule STAC STAC Maps e.g. Sentinel 2 e.g. specific Sentinel 2 scene Band 12 of the scene 27
28. Customization example by DLR 28
29. OGC API - Coverages 29
30. OGC APIs - Coverages • The simplest WCS ever? • Collection as a single coverage • Partial implementation from code sprint 30
31. Coverage extraction • Core allows to extract data from a coverage by: • bbox • datetime • Scaling available too but not implemented yet ...collections/nurc:Img_Sample/coverage? f=image%2Fpng& bbox=-130,20,-100,40 or &subset=Lat(20:40),Long(-90:-70) 31
32. OGC API - Maps 32
33. OGC API - Maps • Draft specification available (GeoServer implements earlier version) • Partial implementation from code sprint • Building block to produce maps, can be attached to collections, but in general, to any resource that can be mapped • E.g., could be a OGC API - process result, that has a “map” sub-resource 33
34. Maps API • Adds a notion of a “style”, listed in collection metadata • Adds a “maps” resource 34
35. “map” resource • Fetches a map in the requested format • Params: width, height, bbox, crs, …. • Unlike WMS GetMap, all params are optional → similar to the GeoServer WMS reflector .../ogc/maps/v1 /collections/topp:states/styles/population/map?f=image/png 35
36. “info” resource (GS specific) • Not part of the standard (used to be in a previous draft) • Still useful (considers scale deps, filters, symbology) • Feature info at given location • Params: “i/j” mandatory, others same as “map” .../ogc/maps/v1/ collections/topp:states/styles/population/map/info? f=text/plain&i=50&j=10 Results for FeatureType 'http://www.openplans.org/topp:states': -------------------------------------------- the_geom = [GEOMETRY (MultiPolygon) with 276 points] STATE_NAME = Washington STATE_FIPS = 53 SUB_REGION = Pacific STATE_ABBR = WA LAND_KM = 172447.205 WATER_KM = 12226.63 PERSONS = 4866692.0 FAMILIES = 1264934.0 HOUSHOLD = 1872431.0 MALE = 2413747.0 FEMALE = 2452945.0 WORKERS = 1830031.0 DRVALONE = 1700872.0 CARPOOL = 282240.0 PUBTRANS = 104403.0 EMPLOYED = 2293961.0 UNEMPLOY = 139216.0 -------------------------------------------- 36
37. OGC API - Tiles 37
38. OGC API - Tiles building block • Finalized specification https://docs.ogc.org/is/20-057/20-057.html • Full implementation based on earlier draft • Adds resources for tiles, tile matrix sets, eventually styles 38
39. Building block, can tile “anything” • /collections/{collectionId} 🡪 data tiles from single collection • /collections/{collectionId}/maps 🡪 rendered tiles from single map • /collections 🡪 raw tiles from multiple collections (list of collections as query param) • /map 🡪 tiles from multi-layer map (list of collections as query param) • /add/your/own/here 🡪 if it can be sliced, API Tiles can expose it 39
40. Tiles resource, URL templates ogc/tiles/collections/topp%3Astates/styles/population/map/tiles/ WebMercatorQuad/{tileMatrix}/{tileRow}/{tileCol}?f=image%2Fpng 40
41. Tiles “metadata” resource • Extension provided by some implementations (not core) • Describes the tiles contents • Can return TileJSON (GeoServer does) { "tilejson": "2.2.0", "name": "topp:states" , "description" : "This is some census data on the states." , "scheme": "xyz", "tiles": [ ".../ogc/tiles/collections/topp%3Astates/tiles/WebMercatorQuad/{z}/{y}/{x}?f=mvt ], "center": [ -89.99999997494392 , 42.525564403512014 , 1.0 ], "bounds": [-124.731422 , 24.955967, -66.969849, 49.371735 ], "format": "application/vnd.mapbox-vector-tile" , "minzoom": 0, "maxzoom": 24, "vector_layers" : [ { "id": "states", "description" : "This is some census data on the states." , "fields": { "STATE_NAME" : "string", "STATE_FIPS" : "string", "HOUSHOLD": "number" ... 41
42. Other APIs 42
43. OGC API - Styles • Building block to describe styles for a resource • In GeoServer a stand-alone API • Implements early draft. Specification is slow moving. 43
44. OGC API - Styles - example Basic metadata info (yeah, I did not fill it yet, no love lost for metadata!) Access to style source, native (CSS) and converted (SLD) when possible List of layers involved in the style (could have many) and attributes used in each (style editor can use them to check compatibility with available data) The style identifier 44
45. DGGS related APIs • Discrete Global Grid System • A way to describe position and accuracy as a hierarchical pyramid of cells rHealPix (equal area) H3 (equal distance) 45
46. DGGS related APIs • Access to zones, neighbours, children, mapping to point/polygons • DAPA style aggregation API: aggregate over area, time, or both 46
47. Moving forward 47
48. Next steps - code • Move from community module to extension • At least for Features • Waiting CQL2 and its implementation • Complete outdated/partial implementations • Tiles • Coverages • Maps • More extensions • Features: property selection, transactions • More APIs • processes • records 48
49. Next steps - users/deploys • Hopefully get more uptake/usage • Currently few deployments (research institutes) • More hybrid deployments (both classic services and OGC APIs) • More front-end support (e.g., MapStore) • Overall hopefully more business around it 49
50. That’s all folks! Questions? info@geo-solutions.it 50