Support OGC API - Features

[jjspace]

The Spec

This issue is to track adding full support for the OGC API - Features spec as well as any discussion around the process.

The spec currently includes 5 parts with parts 4 and 5 currently under draft. The initial plan will be to support Part 1: Core with others as follow up tasks. I currently do not expect us to support Part 2 which adds CRSs which Cesium already does not do much work with.

• OGC API - Features - Part 1: Core corrigendum, version 1.0.1 standard
  • Latest Editor's Draft of next version of OGC API - Features - Part 1: Core
  • ISO 19168-1:2020 Geographic information - Geospatial API for features - Part 1: Core standard
• OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum, version 1.0.1 standard
  • Latest Editor's Draft of next version of OGC API - Features - Part 2: CRS by Reference
• OGC API - Features - Part 3: Filtering, version 1.0.0
• OGC API - Features - Part 4: Create, Replace, Update and Delete draft
• OGC API - Features - Part 5: Schemas draft

Format/Encoding

The spec does not mandate any specific encoding or format but strongly favors HTML and GeoJSON with additional suggestions for GML. We will focus the initial implementation only around GeoJSON (especially since we already support it) with other formats being optional secondary efforts in the future as requested.

Side note: the API does not dictate a specific way to designate what format to serve. I believe most servers will implement this with the content type in headers but another suggestion from the Spec is to use a f=[format] query parameter which I've observed utilized in other libraries and servers so my current assumption is this is one of the more generally accepted methods.

Other implementations

Just listing off some other implementations I've found. Mainly from this list

• ogcapi-js - lightweight and focused on the Features API
  • Works well but I don't see any way to control authentication beyond adjusting query params for every request. May not work with header auth?
• ogc-client - supports multiple OGC specs
  • Similar auth concerns. Allows setting global fetch options for the whole client which could make it hard to use multiple sources
  • The API seems more focused on exploring a service completely and may not fit our needs and use case as closely
  • Only works in browser as it relies on window internally

Example data

Just an assortment of data sources from servers that we know support the OGC Features API and we can use for testing during implementation

• National Land Survey of Finland seems to have a bunch of data
  • Free but needs an API key - Instructions for using the API key
  • Geographic names (OGC API Features)
  • Technical description – Topographic Database (OGC API Features)
• https://demo.ldproxy.net/ Demos using ldproxy but has a handful of different data that we can view
  • Data has a mix of areas, lines and points which is useful
  • Supports an HTML representation so it's really easy to explore the data without another viewer. Just add ?f=json to get the GeoJSON representation
  • Some of these are very large datasets, for example this one of road network nodes has over 10,000 points which could be useful for stress testing or any loading optimizations
• ArcGIS also seems to have OGC Features as an option but I have not explored it much yet
  • We may be able to use the API key we already use
  • Work with OGC Features services—ArcGIS Server | Documentation for ArcGIS Enterprise
  • Tutorial: Style features | CesiumJS | Esri Developer
• Please mention more if you know of good ones!

[jjspace]

I've created an example sandcastle to explore loading different "providers" for OGC Features APIs and visualizing them. Currently it uses the finland and ldproxy data above. This lets us easily explore the data itself but also start to get a feel for the process of managing said data with our underling GeoJsonDataSource objects. As I start implementing our new Provider class/classes I can swap out parts of this sandcastle and still see what it's like to view the data.

I've started working on this in the ogc-features branch which currently has that sandcastle in the developer gallery

Some initial thoughts and observations from this process that we should discuss:

1. GeoJSON doesn't de-duplicate data
   1. With the "pagination" and bbox and other filtering options of the Features API it's very easy/likely to load the same features multiple times. Ideally we should not create duplicated entities but I'm not sure what the best approach to that is
   2. The Features API dictates that every feature should have a unique id even if the GeoJSON spec itself doesn't, can we use this?

   The Core requirements class only requires that the feature URI is unique. Implementations MAY apply stricter rules and, for example, use unique id values per dataset or collection.

   3. In the examples I've seen thus far all features do include that id property
2. How can we access the extra properties of responses like numMatched?

   Each page may include information about the number of selected and returned features (numberMatched and numberReturned) as well as links to support paging (link relation next).

   1. I've also seen some of the samples return an itemCount property on the top level /collections and /collections/collectionId} routes. This is not defined in the spec but could be useful if it's fairly standardized in actual implementations.
   2. When loading data to GeoJsonDataSource we generally provide the url not the json itself and when it's parsed it ignores these extra values. Is there an easy way to expose these instead? If we load the json and pass it to the data source instead we could grab them but I have concerns over memory at that point.
3. How do we handle paging?
   1. How much does our provider control internally vs the consumer?
   2. Should we always try loading all data and only do paging/bbox opti internally?
   3. Or should it be exposed to the user and they control requesting more pages?
4. How should we handle the data source? All parsed into a single GeoJsonDataSource? or multiple?
   1. If multiple, how should we handle them? Also think this would complicate the de-duplication effort
5. Query params and Headers may be a little tricky or a pain to preserve and pass through to every request
   1. iTwin will need an auth header
   2. The Finland data needs an api-key query param (and breaks with the f=[format] query param)
   3. Probably not tooo much different than what we do for 3DTiles but needs to be thought of. This seemed to be one of the the main pitfalls of the libraries I tried.

CC @ggetz any thoughts?

[jjspace]

Bumped into an old issue with the Vineyard sample data that I opened a fix for in #12460

The bigger complication/annoyance I discovered today is that the spec does not provide a defined requirement for how to do paging other than the limit param. The ldproxy pages use a combination of offset and limit to do paging so I assumed offset was standard but the Finland data does not support offset and will actually 400 if it's in the request. The Finland data instead seems to rely on next links with an obscure next code

The only true requirements for the /items route we can rely on to exist are limit, bbox, and datetime. The response from the /items route SHALL include a links property or header but it's only required to include the self and alternate links. It SHOULD include a next link but isn't required.

This will all make paging or requesting more data complicated... Probably need to discuss further