nlsfi/hakunapi

OGC API Features Java server

Hakunapi OGC API Features Server

A server implementation of OGC API Features

• OGC API - Features - Part 1: Core
• OGC API - Features - Part 2: Coordinate Reference Systems by Reference
• OGC API - Features - Part 3: Filtering and Common Query Language (CQL2)

A server implementation of OGC API Features (follow development @ https://ogcapi.ogc.org/features/)

Focus on:

• Simple features backed by a PostGIS database
• High performance (achieved with streaming and by reducing the amount of garbage created)

hakunapi-simple-servlet module builds into a "off-the-shelf" OGC API Features server that you drop into your servlet container and configure with an outside configuration file.

hakunapi can also be used as a "framework" for building your own customized implementation (for example if you want to support Complex Features). The framework is modular and the modules should fit together well, you are free to mix-and-match.

Contributing

See CONTRIBUTING.md

Example

Check out Finnish addresses

hakunapi's Issues

Allow source modules to perform CRS transformations

This might not be that big of a change?

Use NOPProjectionTransformer and HakunaPropertyGeometry will provide the raw (already transformed) value via its' mapper function.

Fix conformance/requirements classes

Conclusion 2023-04-21

Closing this issue. Originally opened because Teams Engine compliance tests on demo service based on Hakunapi complained about some requirements ("Precondition: requirement class http://www.opengis.net/spec/ogcapi-features-2/1.0/req/crs must be implemented"). However this referred to a standard requirement class (req), not to a conformance class (conf).

Hakunapi currently provides conformance classes in conf form when requested by /conformance resource as specified by code ConformanceClass.java. This should be correct and so this issue is closed. If there are some services based on Hakunapi that uses req form, those services must be fixed.

The demo service should be fine:
https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/conformance

Issue description 2023-04-06

Not clear is this an issue with the OGC API Features standard definitions (that has conflicting definitions) or an issue with Hakunapi implementation.

OGC API - Features - Part 2

OGC API - Features - Part 2 (https://docs.opengeospatial.org/is/18-058r1/18-058r1.html) has some conflicting definitions:

• chapter 2: conformance: http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs.
• chapter 6: Requirements Class Coordinate Reference Systems by Reference: http://www.opengis.net/spec/ogcapi-features-2/1.0/req/crs
• Annex A: Abstract Test Suite (Normative): http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs

OGC API - Features - Part 1

Latest approved standard: https://docs.ogc.org/is/17-069r4/17-069r4.html

Chapter 2 (conformance) defines:

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/gmlsf0
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/gmlsf2
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30

But then chapters 7 - 9 (specifications of these classes) define something other:

http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core
http://www.opengis.net/spec/ogcapi-features-1/1.0/req/html
http://www.opengis.net/spec/ogcapi-features-1/1.0/req/geojson
http://www.opengis.net/spec/ogcapi-features-1/1.0/req/gmlsf0
http://www.opengis.net/spec/ogcapi-features-1/1.0/req/gmlsf2
http://www.opengis.net/spec/ogcapi-features-1/1.0/req/oas30

Chapter 7.4. Declaration of conformance classes has a sample for conformance/ resource:

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
  ]
}

The Annex A: Abstract Test Suite (Normative) :

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/gmlsf0
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/gmlsf2
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30

Hakunapi usage can be demonstrated by demo app (published in #18) : https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/conformance

Hakunapi uses following classes, which is correct according to chapter 2 and (normative) annex A but not correct according to chapters 7-9:

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson
http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html

Also Hakunapi uses following class that's not defined by standard:

http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/gpkg

OGC API - Features - Part 3: Filtering

Latest draft: http://docs.ogc.org/DRAFTS/19-079r1.html

Chapter 2 (conformance):

http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter
http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter

Chapters 6 - 9

http://www.opengis.net/spec/ogcapi-features-3/1.0/req/queryables
http://www.opengis.net/spec/ogcapi-features-3/1.0/req/queryables-query-parameters
http://www.opengis.net/spec/ogcapi-features-3/1.0/req/filter
http://www.opengis.net/spec/ogcapi-features-3/1.0/req/features-filter

Annex A: Abstract Test Suite (Normative)

http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/queryables
http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/queryables-query-parameters
http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter
http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter

Again conflicting definitions on the standard draft.

Hakunapi uses currently

http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter
http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter

Common Query Language CQL 2

Latest draft: https://docs.ogc.org/DRAFTS/21-065.html

Chapter 2 (conformance)

Conformance class	URI
Basic CQL2	http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2
Advanced Comparison Operators	http://www.opengis.net/spec/cql2/1.0/conf/advanced-comparison-operators
Case-insensitive Comparison	http://www.opengis.net/spec/cql2/1.0/conf/case-insensitive-comparison
Accent-insensitive Comparison	http://www.opengis.net/spec/cql2/1.0/conf/accent-insensitive-comparison
Basic Spatial Operators	http://www.opengis.net/spec/cql2/1.0/conf/basic-spatial-operators
Spatial Operators	http://www.opengis.net/spec/cql2/1.0/conf/spatial-operators
Temporal Operators	http://www.opengis.net/spec/cql2/1.0/conf/temporal-operators
Array Operators	http://www.opengis.net/spec/cql2/1.0/conf/array-operators
Property-Property Comparisons	http://www.opengis.net/spec/cql2/1.0/conf/property-property
Functions	http://www.opengis.net/spec/cql2/1.0/conf/functions
Arithmetic Expressions	http://www.opengis.net/spec/cql2/1.0/conf/arithmetic
CQL2 Text encoding	http://www.opengis.net/spec/cql2/1.0/conf/cql2-text
CQL2 JSON encoding	http://www.opengis.net/spec/cql2/1.0/conf/cql2-json

Chapter 6 - 8 defines a format like http://www.opengis.net/spec/cql2/1.0/req/basic-cql2 for all conformance/requirement classes mentioned above. And appendix A using conf

OGC API - Common

The standard OGC API - Common - Part 1: Core

• This Standard identifies five conformance classes. The conformance classes implemented by an OGC API are advertised through the /conformance resource on the implementation instance of the API’s landing page. Each conformance class is defined by one requirements class.
• 9.3. Declaration of Conformance Classes
  • ease of access is also supported by the structure of the Conformance Declaration resource. It is a simple list of URIs. This is a structure that requires almost no parsing and little interpretation and is designed to be accessible to even the simplest client.
  • example: http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core
• 10. Encoding requirement classes, defines for example:
  • http://www.opengis.net/spec/ogcapi-common-1/1.0/req/html
  • http://www.opengis.net/spec/ogcapi-common-1/1.0/req/json
• A.4. Conformance Class JSON
  • Identifier: http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/json
  • Subject: http://www.opengis.net/spec/ogcapi-common-1/1.0/req/json

This would clearly suggest that we should use the identifier, here for JSON the identifier is http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/json to announce (for example in /conformance resource) a conformance class that is defined by a requirement class.

But then this standard strikes again.

B.2. Conformance Examples

This example response in JSON is for an implementation of the OGC API-Common Standard that supports OpenAPI 3.0 for the API definition, as well as HTML and JSON as encodings for resources.

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/core",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/landing-page",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/oas30",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/html",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/json"
  ]
}

This would suggest using http://www.opengis.net/spec/ogcapi-common-1/1.0/req/json as an identifier!

Analyze use cases and implementation choices for supporting OGC Features and Geometries JSON

Background

See the official github page about: OGC Features and Geometries JSON that is OGC's candidate standard.

According to documentation OGC Features and Geometries JSON will

• include the ability to use Coordinate Reference Systems (CRSs) other than WGS84
• follow the OGC Axis Order Policy,
• allow the use of non-Euclidean metrics, in particular ellipsoidal metrics,
• support solids and multi-solids as geometry types, and
• provide guidance on how to represent feature properties, e.g., including temporal properties.

This might be one of candidate enhancements for Hakunapi after 1.0 version.

Before deciding some analysis is needed:

• use cases and data sets for new geometry types like solids and multi-solids
• how new capabilities of OGC Features and Geometries JSON would be used in vector data products or geospatial APIs by mapping agencies like NLS of Finland
• how to define, implement and document application schemas when producing OGC API Features service that supports 1) GeoJSON content with CRS84 default coordinate system, 2) GeoJSON content with other coordinate systems according to OGC API Features Part 2 (CRS) and it's "Content-Crs" header (that provides also a method for axis-order issue), 3) JSON-FG content with CRS84 (content is same as GeoJSON) or other coordinate systems (content is something different to GeoJSON content)
• implementation choices in Hakunapi (there's some internal notes by NLS of Finland on this topic)

Suggested first implementation targeting Hakunapi 1.1.0 version

Support at least these features first:

• include the ability to use Coordinate Reference Systems (CRSs) other than WGS84
• follow the OGC Axis Order Policy,
• provide guidance on how to represent feature properties, e.g., including temporal properties.

Non goals (for first iteration):

• allow the use of non-Euclidean metrics, in particular ellipsoidal metrics,
• support solids and multi-solids as geometry types, and

Standard conformance classes to be supported (from the draft standard):

• "Core": The Core conformance class extends GeoJSON with additional members that allow Temporal information, extended Geometry information (i.e. geometries in coordinate reference systems (CRS) other than CRS84 which is the GeoJSON CRS, and additional geometry types) and Reference systems information to be encoded in a JSON-FG document. The Core conformance class has a dependency on GeoJSON. This means that a JSON-FG document that conforms to Core must also conform to GeoJSON.

Coordinate reference systems that differ only by axis order do not work

The following request to a collection

• with storageCrs EPSG:3067

/collections/{collectionId}/items?crs=http://www.opengis.net/def/crs/EPSG/0/3047&bbox=6854058.383,333886.496,6854061.684,333893.007&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3047

fails with error:
ERROR: ST_Intersects: Operation on mixed SRID geometries (Polygon, 3067) != (Polygon, 3047)

Document version, code and package management process

The process is developed during implementation of other issues like #5, #6 and others.

What should be documented:

• version management on the Hakunapi repository
• using feature branches and pull requests
• how the main branch is maintained
• triggering GitHub actions to test and deploy code packages
• ....

Fix any issues on Hakunapi modules reported in testing on nls.fi OGC API Features services

After implementing #7.

Query result parsing fails, but /items still return empty HTTP 200 result

When the data types change on the DB side without restarting the hakunapi service, for example a datetime->date change on a column will trigger above error in resultset parsing, but this is not indicated by HTTP 5xx status code.

Restructure servlet modules to allow javax and jakarta based modules in future

Currently modules (https://github.com/nlsfi/hakunapi/tree/main/src) contains:

• "hakunapi-simple-servlet"
• "hakunapi-simple-webapp"

These should be renamed with "javax" extension etc. to support Hakunapi servers with JDK11+ / tomcat 9 / jersey 2 / javax / webapp

This would allow in future similar modules with "jakarta" dependencies (targeting JDK11+ / tomcat 10 / jersey 3 /jakarta / webapp).

Still currently the support for "javax" is the main focus - may change in future.

Publish the demo service in an open endpoint

After #10 is finalized on the repository and tested locally.

To publish a server for OGC API demos by NLS of Finland is used.

Inconsistent links in collections resources when api-key given

For example, a service based on nls.fi version of Hakunapi may output links like:

https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections?api-key=YOUR-API-KEY

{
    "id" : "syvyyskayransyvyysarvo",
    "title" : "Syvyyskäyrän syvyysarvo",
    "description" : "Syvyyskäyrään tallennettava käyrän korkeusarvoa osoittava luku (tekstikohde).",
    "links" : [ {
      "href" : "https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/syvyyskayransyvyysarvo/items",
      "rel" : "items",
      "type" : "application/geo+json"
    }, {
      "href" : "https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/syvyyskayransyvyysarvo/items?api-key=YOUR-API-KEY&f=json",
      "rel" : "items",
      "type" : "application/geo+json"
    }, {
      "href" : "https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/syvyyskayransyvyysarvo/schema?api-key=YOUR-API-KEY",
      "rel" : "describedBy",
      "type" : "application/schema+json"
    }, {
      "href" : "https://avoin-paikkatieto.maanmittauslaitos.fi/maastotiedot/features/v1/collections/syvyyskayransyvyysarvo/queryables?api-key=YOUR-API-KEY",
      "rel" : "http://www.opengis.net/def/rel/ogc/1.0/queryables",
      "type" : "application/schema+json"
    } ],
    "itemType" : "feature",
    "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/3067", "http://www.opengis.net/def/crs/EPSG/0/4258", "http://www.opengis.net/def/crs/EPSG/0/3046", "http://www.opengis.net/def/crs/EPSG/0/3047", "http://www.opengis.net/def/crs/EPSG/0/3048", "http://www.opengis.net/def/crs/EPSG/0/3873", "http://www.opengis.net/def/crs/EPSG/0/3874", "http://www.opengis.net/def/crs/EPSG/0/3875", "http://www.opengis.net/def/crs/EPSG/0/3876", "http://www.opengis.net/def/crs/EPSG/0/3877", "http://www.opengis.net/def/crs/EPSG/0/3878", "http://www.opengis.net/def/crs/EPSG/0/3879", "http://www.opengis.net/def/crs/EPSG/0/3880", "http://www.opengis.net/def/crs/EPSG/0/3881", "http://www.opengis.net/def/crs/EPSG/0/3882", "http://www.opengis.net/def/crs/EPSG/0/3883", "http://www.opengis.net/def/crs/EPSG/0/3884", "http://www.opengis.net/def/crs/EPSG/0/3885" ],
    "storageCrs" : "http://www.opengis.net/def/crs/EPSG/0/3067"
  }

Here a link to items is without API-key, but items?f=json resource has it.

How this should be implemented consistently?

As a reference Hakunapi demo service:

https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections?f=json

{
  "links" : [ {
    "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections",
    "rel" : "self",
    "type" : "application/json",
    "title" : "This document"
  } ],
  "collections" : [ {
    "id" : "addresses",
    "title" : "Simple Addresses",
    "description" : "Addresses of Finlands Buildings",
    "links" : [ {
      "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/items",
      "rel" : "items",
      "type" : "application/geo+json"
    }, {
      "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/items",
      "rel" : "items",
      "type" : "text/html"
    }, {
      "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/items?f=json",
      "rel" : "items",
      "type" : "application/geo+json"
    }, {
      "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/items?f=html",
      "rel" : "items",
      "type" : "text/html"
    }, {
      "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/schema",
      "rel" : "describedBy",
      "type" : "application/schema+json"
    }, {
      "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/queryables",
      "rel" : "http://www.opengis.net/def/rel/ogc/1.0/queryables",
      "type" : "application/schema+json"
    } ],
    "itemType" : "feature",
    "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/3067", "http://www.opengis.net/def/crs/EPSG/0/4258" ],
    "storageCrs" : "http://www.opengis.net/def/crs/EPSG/0/3067"
  } ]
}

There is four items-resource links. Two links to items resource (both GeoJSON and HTML) and separately items?f=json and items?f=html links.

Axis order of response coordinates does not follow the requested CRS axis order

With a collection like

{
  "id" : "jobs",
  "title" : "jobs",
  "description" : "jobs",
  "links" : [ ... ],
  "itemType" : "feature",
  "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/3903" ],
  "storageCrs" : "http://www.opengis.net/def/crs/EPSG/0/3903"
}

and requesting items with ?crs=http://www.opengis.net/def/crs/EPSG/0/3903 the axis order of the response is not reversed (has E,N), while the CRS has N,E.

There seems to be some confusion on the axis order that should be followed on the response (crs-based or always geojson-easting-northing), but the consensus seems to be on prior arragement: client must understand what it requests, and the response header Content-Crs defined in part 2 now "explicitly and unambiguously" defines the response coordinate contents => axis order follows crs.

geopython/pygeoapi#1174 (comment)
qgis/QGIS#52366 (comment)

This breaks hakunapi-based OAPIF layer use for example in QGIS (3.28.7+, 3.30.2+, 3.32.0+) where the implementation was changed to flip the order according to the crs.

Missing spatial extent doesn't cause warnings / errors

Currently hakunapi doesn't require spatial extent to be configured for collections with geometry properties. This can lead to issues that are difficult to debug as some clients (ETS validator for example) use spatial extent of a collection to determine if the collection is a spatial feature collection.

Support splitting Hakunapi configurations to multiple files

In some services Hakunapi feature configuration files are relatively large.

In this enhancements Hakunapi read a folder containing multipe configuration files and merges these when starting a server.

Support for Oracle data store

Support for Oracle data store to provide OGC API Features service.

Some thoughts was discussed on pull request #86

Implement demo service describing capabilities and setup of feature server based on Hakunapi

A "minimal" sample feature server with a small spatial dataset (with a valid open data license to allow bundling).

This sample should demonstrate:

• how to setup a feature server based on Hakunapi
• describe basic configuration options for dataset integrations, data table mappings and feature collections (according to OGC API Features / Open API based service)
• work as a template for Hakunapi users to help them get started

Support for publishing programmable application schemas of feature objects and codelists provided by OGC API Features service

According to OGC API Features discussion Support for OpenAPI 3.1 proper support for application schemas has waited OpenAPI version 3.1.

OpenAPI 3.1 has been released in 2021-02-16.

Related to OGC API Features there is proposal for an extension called OGC API - Features - Part n: Schemas. And there is a project page in GitHub for it. However no information about schedule for first draft?

Maybe there's two approaches to publish schemas in distant future:

• schema information included in a OpenAPI 3.1 document published in /api resource (based on separate conformance class to Open API 3.0 document, that is indicated by the conformance class http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30)?
• schema information published according to future "OGC API - Features - Part n: Schemas" specification in some kind of returnables resources?
  • returnables (default): The schema will specify an object as it is returned at the /collections/{collectionId}/items/{featureId} endpoints of the collection.

Enable f=json parameter in collection and metadata resources

See #18 for background discussions.

Fix Open API document generated by Hakunapi and used by demo service

Currently at least Open API document represented as JSON provided by https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/api.json fails when analyzing it in Swagger editor (or other tools).

Gives multiple errors like:
Structural error at paths./.get.responses.200.content.text/html
should NOT have additional properties
additionalProperty: exampleSetFlag
Jump to line 33

When accessing Open API document as HTML content in browser (https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/api) HTML document is shown without errors.

The issue is related to the exampleSetFlag property (that informs "whether an example is set to null intentionally") in OpenAPI class of Hakunapi - this property should not be serialized to Open API document output.

Tool to help creating Hakunapi configuration templates

For example a CLI tool (or other user interface) that reads database schema and creates Hakunapi configuration templates (mapping database tables to feature collections).

Update OGC API Features implementation list

https://github.com/opengeospatial/ogcapi-features/tree/master/implementations
https://github.com/opengeospatial/ogcapi-features/blob/master/implementations/servers/nlsfi.md

Feature request: Add a generic configurable usage monitor/telemetry for operations GetCollectionItems, GetCollectionItemById

Feature request

Implement generic, extendable and configurable telemetry/usage monitor for operations GetCollectionItems, GetCollectionItemById.

Add interfaces to hakunapi-core
Add basic logging telemetry implementation as hakunapi-telemetry module.
Add webapp with telemetry as hakunapi-telemetry-webapp-javax module

Add a basic implementation based on SLF4J/Log4j
Add a configurable OpenTelemetry appender for SLF4J.

Basic operations
Add functionality around GetCollectionItems and GetCollectionItemById to support storing request-response information to a Span.
Store Span as JSON record for each request with collection response counts and a configurable set of headers from HTTP request

2024-01-18 12:44:52.828|INFO |fi.nls.hakunapi.telemetry.items||{"username":"<username>", "example-collection":15 "}

Logging configuration

• Logging configuration for appenders and loggers with log4j2.xml

Service configuration

• Add telemetry and header configurations to hakunapi properties file

telemetry.mode=json
telemetry.logger=fi.nls.hakunapi.telemetry
telemetry.collections=example-collection,...
telemetry.fields=username,...
telemetry.fields.username.header=remote-user

Optional opentelemetry implementation

Add functionality and configuration to connect SLF4J to opentelemetry appender

Add documentation about all Hakunapi modules

There should be introduction documentation (features, technical requirements, dependencies, ..) about each modules the Hakunapi repository provides.

For example a separate readme.md for each module folder.

Ensure bbox queries work correctly when bbox spanning the antimeridian

For example a query like with bbox spanning the antimeridian:
https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/collections/addresses/items?bbox=160.6,-55.95,-170,-25.89

This is empty by dataset, should test and validate with some global dataset.

date-time type parameters accept UTC timestamps only

Using datetime (or a custom attribute parameter with for example DatetimeRangeMapper) does not accept other than UTC timestamp values as input.

• ?datetime=2020-01-01T00:00:00Z works
• ?datetime=2020-01-01T02:00:00+02:00 fails with 'datetime' value could not be parsed

OAPIF spec says RFC 3339, 5.6, which allows offsets.

Support for GeoPackage data source with documentation and sample code

What?

• support for providing OGC API Features service from GeoPackage data source
• documentation for setting up GeoPackage based OGC API Service
• sample code extending demo in https://github.com/nlsfi/hakunapi/tree/main/examples
• maybe also demo service running in a docker container and deployed on a managed cloud service

This was piloted late 2023 by pull request #74.

Related pull requests: #86 and #45

Default HTML templates don't have links to JSON representation

After implementing #25 it will be possible to control the content-type of each resource in the api with a query parameter. It would be nice if the default HTML templates used by hakunapi would include a link to the JSON representation of the current resource. This is pretty common functionality in an OGC API Features implementation.

Analyze needs and requirements for Compliance Certification

https://www.ogc.org/resources/compliance/
https://www.ogc.org/resources/uncertified-products/

https://github.com/opengeospatial/cite/wiki/Usage-Of-The-Compliance-Certification-System

Support for Tomcat 10 and Jakarta

Initial implementation in pull request #85

Change all occurrances of "Powered by hakuna" into ...hakunapi

https://github.com/search?q=repo%3Anlsfi%2Fhakunapi+powered&type=code

Test Hakunapi packages on nls.fi projects producing OGC API Features services

After implementing #6.

OGC API Features services by nls.fi using Hakunapi:

1. Osoitteiden kyselypalvelu (OGC API Features)
2. Nimistön kyselypalvelu (OGC API Features)
3. Kiinteistötietojen kyselypalvelu (OGC API Features)
4. ...

Public Hakunapi package version are tested on development environment and issues noticed are reported here.

Java version support (JDK11 and JDK17)

Previous versions of Hakunapi supported also Java 8 - this can be removed.

Requirements for Java version support (minimum):

• JDK11
• JDK17

Also related to #16 other java servlet related requirements:

• currently the main target: JDK11+ / tomcat 9 / jersey 2 / javax / webapp
• in the future maybe also: JDK11+ / tomcat 10 / jersey 3 /jakarta / webapp

source-postgis: Add support for Unix Domain Sockets

This could be useful for users running postgis on the same machine as hakunapi.

Support for containerized deployment and cloud service hosting

Support and documentation for:

• deployment as a Docker container (actions, hakunapi-simple-webapp bundled as a container, etc)
• hakunapi-simple-webapp published in a container register (GitHub, Docker or Azure)
• example app (https://github.com/nlsfi/hakunapi/tree/main/examples/finnish_addresses) also as a container with instructions
• example app container deployed to a cloud service (ie. Azure App Service) to host a demo service

Currently the finnish_addresses example is available online (https://beta-paikkatieto.maanmittauslaitos.fi/inspire-addresses/features/v1/) without access restriction, but not in a managed cloud service.

Enhanced support for OGC API Features : Part 3 (Filtering) and CQL 2 standards

Background

The support for OGC API Features : Part 3 (Filtering) and CQL 2 standards in Hakunapi has been developed in late 2021 and early 2022 based on the draft standards versions. Still (2023-05-29) waiting for standards to be approved. At least after approval also support in Hakunapi should be enhanced.

First need to analyze and document

• which features and conformance classes are currently supported
• which features and conformance classes not currently implemented are needed by NLS of Finland and other user's use cases
• then decide what Hakunapi should support and implement those features

Links (drafts)

OGC API Features

• Latest drafts (2023-05-31):
  • OGC API - Features - Part 3: Filtering draft (1.0.0-rc.2-SNAPSHOT)

Common Query Language (CQL2)

• Latest drafts (2023-05-31) or at least this was referenced by Part 3 version 1.0.0-rc.2-SNAPSHOT :
  • Common Query Language (CQL2) 1.0.0-rc.1

Add support for Link headers

Currently hakunapi doesn't support Link headers. This is problematic with GeoPackage (and less used GML) as there's no way to access for example next link (which is crucial for pagination).

Add option to configure HTML template external dependencies

Current HTML application templates with external resources does not work when web server has strict security settings.

Todo

Update ftl template resource references to latest versions.

Add configuration option to load custom ftl templates from an external directory.
(This includes possibility to use a npm built application)

# optional external template directory for ftl templates
formats.html.templates.dir=/var/www/html/features/templates

WFS3-jäänteet

WFS3 näyttää vielä kummittelevan joissakin paikoissa, mahtaako olla tarkoitus?

• tiedosto WFS3Service.java
• kommentti tiedostossa ConformanceOperation.java
• conformance class -polku tiedostossa ConformanceClass.java
  DIRECT_TILE("http://www.opengis.net/spec/wfs/3.0/vt/req/core/direct-tile-access-path-api")

Tuo direct-api on määritelty noin insinöröintiraportissa https://docs.ogc.org/per/18-078.html#direct_access_path, mutta sen kohdetta ei oikeasti ole olemassa.

Onkohan tämä GPKG-conformance myös jostain kokeilusta peräisin:
GPKG("http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/gpkg"

Pitäisikö noihin kohteisiin (DIRECT_TILE ja GPKG), joita ei oikeasti löydy, lisätä kommentit?

Integrate public Maven repository to nls.fi internal package repository

After implementing #5.

Add documentation about configuration of features servers based on Hakunapi

Documentation about different use cases (under "docs" folder on the repository):

• simple features
• complex features
• etc.

This also relates to #10 .

Fix the name of the link: describedBy -> describedby

See opengeospatial/ogcapi-features#338

The name is set here and probably there is nothing else to fix but I am not sure.

hakunapi/src/hakunapi-simple-servlet-javax/src/main/java/fi/nls/hakunapi/simple/servlet/javax/operation/CollectionMetadataUtil.java

Line 104 in 867afe4

String rel = "describedBy";

Implement actions to build, test and upload Hakunapi packages to public Maven repository

Alternatives:

1. Maven Central
2. GitHub packages

Maven Central requirements and guides:

• https://central.sonatype.org/publish/requirements/
• https://dzone.com/articles/how-to-publish-artifacts-to-maven-central

About signing process and GPG keys (when publishing on Maven Central)

• https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
• https://central.sonatype.org/publish/requirements/gpg/#distributing-your-public-key
• https://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html
• https://www.simplify4u.org/sign-maven-plugin/

About group id on Maven Central

• https://central.sonatype.org/publish/requirements/coordinates/

The alternative 1 was selected, steps:

1. (OK) group id "fi.nls.hakunapi" registered on Maven Central
2. (OK) signing process tested with a test GPG key PR #15
3. signing process with a production GPG key
4. publish pre-release version of Hakunapi 1.0 on Maven central