Changelog

A large number of dependencies have been updated across the Apiman codebase to improve security. By Marc Savy (@msavy).

[gateway]: Use UTC for Time Restricted-Access-Policy. The Gateway used the configured local (server) time instead of UTC while applying the rules. This could have lead to a mismatch between configuration (UTC) and execution. By Florian Volk (@volkflo).

[manager-ui]: Fix CSS issue with metrics popover legend being white/invisible. By Marc Savy (@msavy).

[common-config]: Fix an edge case in EnvLookup where List.of might be used with a null element which results in a NPE and metrics not rendering with certain configurations. By Marc Savy (@msavy).

[gateway-vertx]: you can add a list of additional allowed-issuers in your Gateway API Keycloak Authentication config. This better supports situations where your Keycloak server returns multiple different issuers, for example for internal vs external domains, Docker, K8s, etc. By Marc Savy (@msavy).

A large number of dependencies have been updated across the Apiman codebase to improve security. By Marc Savy (@msavy).

[containers/docker-compose]: to support a change in Keycloak’s behaviour, we now set allowed-issuers in the Vert.x Gateway API authentication configuration to allow both internal and external issuers. By Marc Savy (@msavy).

[gateway-vertx]: allow access to Vert.x Gateway API’s /system/status endpoint without auth. This allows health checks without needing to pass around auth credentials and/or relying on 4xx errors. By Marc Savy (@msavy).

[gateway-vertx]: array values are now always correctly substituted in Vert.x Gateway configuration. By Marc Savy (@msavy).

[portal]: show REST API documentation even when user not logged in. By Bastian Gembalczyk (@BastianGem) and Florian Volk (@volkflo).

[gateway-vertx]: do not include null/empty path elements in Keycloak discovery URI. If your Vert.x Gateway API was unable to speak to Keycloak because it had an unexpected null in the URI, this should fix it. By Marc Savy (@msavy).

[distro-ddl]: Multiple small MSSQL (Microsoft SQL Server) DDL fixes. If you are using MSSQL, you should set the Java system property hibernate.auto_quote_keyword=true — in WildFly you can put this into the properties section of standalone-apiman.xml. By Marc Savy (@msavy).

[manager-api-jpa]: Allow deletion of org with contracts. It should be possible to delete an organization with retired entities. By Florian Volk (@volkflo).

[gateway-engine-vertx]: Ensure API is resolved before using it. An old contribution did not respect asynchronous patterns properly. By Marc Savy (@msavy).

[metrics-es]: allow logging metrics to file with write-to option. To facilitate scrape-based metrics patterns, this commit allows Apiman’s ES metrics to be written to a log file as JSON via whichever logging framework you are using (asynchronously). You can set any combination of remote (ES server) or/and log (local). By Marc Savy (@msavy).

A variety of dependencies have been updated across the Apiman codebase to keep users secure. If you don’t want to upgrade, speak to your long-term support provider.

[manager-api-rest]: Apiman Manager API now has an OpenAPI v3 schema! You can access this at /openapi.json or /openapi.yml. For example, http://localhost:8080/apiman/openapi.json. By Marc Savy (@msavy).

Default plugin registry and API catalogue JSON files are now in the GitHub release, rather than directly in the repository. By Marc Savy (@msavy).

Converted Apiman into a monorepo (as far as possible). Apiman plugins, default API catalogue, default plugin registry, developer portal, docker images, amongst others, have been painstakingly merged in. CI pipelines have also been updated to reflect this. Multi-repository releases are difficult with GitHub CI, so this will hopefully make more frequent releases much easier. By Marc Savy (@msavy).

[manager-api-rest]: Removed obsolete Qmino API documentation generator. I would like to thank the Qmino team for their support over the years. By Marc Savy (@msavy).

fix[gateway-vertx]: in Keycloak discovery code getAllowedIssuers check was mistakenly inverted. By ronimhd.

fix[manager-api]: register subtypes for deserializing policy probe response, this step was inadvertently removed during refactoring. By Florian Volk (@volkflo).

fix[ui]: move validation function for IP list into validate function to ensure list valid when switching between IP policies. By Florian Volk (@volkflo).

fix[gateway-engine-es]: throw ClientNotFoundException if client not found when unregistering. By Florian Volk (@volkflo).

[manager-api]: Perform unregister only if client is in correct state. By Florian Volk (@volkflo).

[manager-api] Events: versioned events are now emitted inside Apiman for a number of important business actions. These are consumed internally within Apiman, but are also inserted into a transactional outbox inside the database using the CloudEvents format. You can use CDC software, such as Debezium to integrate Apiman’s events into your messaging platform of choice, such as Apache Kafka. A wide variety of rich business functionality can be enabled via this integration. By Marc Savy (@msavy).

[manager-api] Notifications: notifications for important events are now generated and sent to the appropriate user(s) and/or group(s). This is driven by the event system. For example, when an API requires approval, all users with the apiEditor permission will receive an in-browser notification and email notification. In-browser notifications can be seen by pressing the bell in the top-right corner of the screen. Notifications can be disabled entirely in apiman.properties. By Marc Savy (@msavy).

[manager-api] Email notifications and templates: a fully templated and i18n-friendly email notification system, which is driven by the events subsystems. This can easily be customised by the user to change the look-and-feel or text. Email notifications are disabled by default in apiman.properties. By Marc Savy (@msavy).

[manager-api] API signup approvals: an API version can be offered via different plans. You can now choose to require that a user receive explicit approval before being allowed access to the API. Appropriate notifications (including emails, if enabled), are sent to all relevant parties for signup, approval, rejection, etc. By Marc Savy (@msavy).

[distro] Docker compose quickstart distro: provides an out-of-the-box full platform deployment of Apiman, broken down into its components in a way that is more representative of a real-world deployment. By Marc Savy (@msavy).

[manager-api] User locale: where possible, the user’s preferred locale is now stored in their Apiman profile any async events that require it, such as emails. By Marc Savy (@msavy).

[manager-api] Implicit permissions system (discoverability): an implicit read permissions system that layers on top of the explicit permissions systems that already exist in Apiman. It allows API providers to expose specific APIs to consumers who are not members of their organisation. For example, if you have an API that you want non-members to be able to consume, this feature addresses your needs. For more, see Apiman Discoverability. By Marc Savy (@msavy).

[manager-api] Developer portal API: designed specifically for our Apiman Developer Portal, this API allows anonymous access to certain Apiman APIs for browsing, with increased access for logged-in users. Various extensions to the data model for newer features. By Marc Savy (@msavy).

[ui] Developer portal manager UI: a new tab called in the Apiman Manager UI which is available when creating an API. This enables the API provider to decide various portal-related settings, plan ordering, which plans are visible to which users, markdown documentation for developers, API logo, etc. By Marc Savy (@msavy).

[ui] Developer portal UI: an entirely new user interface for Apiman, dedicated to API consumers. The portal provides a focussed, slipstreamed, and customisable/skinnable experience, without all the noise of the main UI’s advanced features. The devportal repository is current separate, please refer to their changes independently. This is different from the previous developer portal that you may have seen with Apiman 2.x. A considerable amount of work has gone into this project, and huge credit goes to the sponsors and contributors.

[gateway-core] Policy probes: allows policies to expose their internal state to the Apiman Manager for interrogation. For example, "what is the current rate limit status for X?". Even custom policies can implement this new functionality. By Marc Savy (@msavy).

[metrics-es] Elasticsearch metrics can optionally collect custom request headers, response headers, and query parameters, according to regular expressions provided by the user. The Elasticsearch schema will be extended dynamically. This feature required a change to the core of Apiman, but was done in a backwards compatible way. Other metrics implementations should be able to make use of this change (sponsorship welcome). By Marc Savy (@msavy).

[manager-api-jpa]: Apiman Manager automatic database migrations (from 3.0.0.Final onwards): Liquibase SQL/DDL migrations have been refactored, with the Liquibase CDI Migrator integrated into the project directly. This stores which migrations have been run before, and applies only the latest SQL migrations for the Apiman Manager SQL backend, so a full export-import for every new Apiman version should not be needed any more. It can be disabled, if you prefer. By Marc Savy (@msavy).

[distro]: Standalone docker images: standardised and supported standalone images for Apiman that will be useful for users planning to use Apiman in a real-world deployment. By Florian Volk (@volkflo).

[ui] Quick navigation sidebar: on the left-hand side of the Apiman Manager UI there is now a multi-tiered sidebar to navigate quickly to various areas of the Apiman Manager UI. By Florian Volk (@volkflo) and Bastian Gembalczyk (@BastianGem).

[logging]: Apiman logger is now used everywhere; it can be accessed statically from anywhere (including Apiman policy plugins), via ApimanLoggerFactory.getLogger(YourClazz.class). The previous approach tried to be very flexible, but ended up mostly being inconvenient and clumsy. An appropriate logger implementation is selected for each platform Apiman ships on, rather than leaving it for the user. By Marc Savy (@msavy).

[build]: introduced the Apiman Parent BOM (io.apiman:apiman-parent:<version>). This contains managed versions of all Apiman Maven dependencies, which may be useful for plugin authors. By Marc Savy (@msavy).

[config]: Better config parsing for Apiman’s components (e.g. when reading from apiman.properties). Not rolled out everywhere, but provides a more unified experience with much better error messages and type validation. By Marc Savy (@msavy).

[distro-wildfly]: Developer portal added to the WildFly Quickstart distro. The portal can be accessed at http://localhost:8080/portal, and you can customise the portal by editing its various configuration options in standalone/configuration/portal/assets/. By Marc Savy (@msavy).

[build]: fastbuild.sh script to build apiman as fast as possible in parallel using mvnd or mvnw. It skips test and javadoc. By Marc Savy (@msavy).

[policies]: blocklist/allowlist (fka. blacklist/whitelist) add support for IPv6, CIDR, ranges, etc. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2027

[manager-api]: support OpenAPI v3 endpoint replacement. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2053

[gateway-engine-core]: thread-safe batched non-blocking metrics consumer. This is useful if you are creating a metrics implementation, and you want it to have good performance. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2126

[metrics-influxdb]: add support for Influx 1.x, including use of an authorization token. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2127

[manager-api]: add column order index for Api Plans so users can explicitly order plans in UI. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2159

[manager-api]: add rejection to contract approval workflow. By Florian Volk (@volkflo) in https://github.com/apiman/apiman/pull/2175

[policies]: performance and memory optimisations for caching policy, blocklist/blacklist policy, and allowlist/whitelisting policy. By Marc Savy (@msavy).

[ui]: Lazy load API DevPortal page using $ocLazyLoad, this avoids the Apiman Manager UI initial download being larger. By Marc Savy (@msavy).

[build]: Java 11+ is the minimum supported version to compile and run Apiman.

[distro]: Apiman Docker images now published to both GHCR (GitHub Packages) and DockerHub. By Marc Savy (@msavy).

[build]: Apiman Docker images have been refactored to accept `--build-arg`s for most variables, such as Apiman’s version, JDBC driver versions, etc. By Marc Savy (@msavy).

[build]: Bumped Keycloak to 16.0.2. By Marc Savy (@msavy).

[ui]: Upgraded Apiman Manager UI to latest AngularJS. By Marc Savy (@msavy).

[ui]: Refactored Apiman Manager UI build system to use Webpack 5. Although this was a considerable investment of time and effort, it enabled us to make the build smaller, with a much better developer experience, whilst eliminating some bugs associated with our old approach. By Marc Savy (@msavy).

[ui]: Major refactor of Apiman Manager UI to bring most deps up to date: Angular 1.8, Typescript 4.4.x, JQuery, Lodash, etc. By Marc Savy (@msavy).

[manager-api]: Where possible, transactions are now controlled via annotations. Currently, this uses a custom CDI interceptor, but we’ll likely use container-managed TX in the future (likely by reducing to a single Apiman Manager platform). By Marc Savy (@msavy).

[metrics-es]: If the Elasticsearch metrics buffer is completely full then metrics records will be dropped. By Marc Savy (@msavy).

[distro]: Bump the Apiman WildFly distro to WildFly 23.0.2.Final. By Marc Savy (@msavy).

[policies]: Rename policies: 'blacklist' → 'blocklist', and 'whitelist' → 'allowlist'. If you have an existing policy with the old names, it will continue to work without issue. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2040

[ui]: Update swagger-ui to v4. By Florian Volk (@volkflo) in https://github.com/apiman/apiman/pull/2066

[manager-api]: Refactor Apiman Manager code to have service layers, so that business logic is not in presentation layer. This will likely be a multiphase process, and ideally we will move towards DDD-style code over time. By Marc Savy (@msavy).

[manager-jpa]: Remove most uses of JPA Criteria API and replace with Blaze-Persistence. This is a modern reinterpretation of the Criteria API concept that is usable by mere human beings such as Apiman’s maintainer. Thanks to Christian Beikov for his assistance in fixing a show-stopper bug that Apiman exposed in Hibernate when using Blaze-Persistence. By Marc Savy (@msavy).

[distro]: bump minimum required version of Postgres from 9 to 11. PGES 9.x does not support the create or replace procedure syntax we use, and the 9.x lineage is not supported upstream anymore.

[distro]: Apiman is no longer distributed with the Keycloak Server Overlay, as this has been discontinued by the Keycloak team. You will need to point Apiman to a Keycloak server that is run separately (see the Docker Compose distro for examples). By Marc Savy (@msavy).

[distro]: Apiman Manager API no longer supports Elasticsearch as a backend store, this is now RDBMS/SQL only. We still maintain full support for Elasticsearch for metrics/analytics. Consequently, we have removed ESStorage and associated code. See: AEP 2: Drop Elasticsearch as Manager API database in Apiman 3 (keep for metrics, gateway, etc). By Marc Savy (@msavy).

[distro]: Java 8 is no longer supported in the community project.

[ui]: Fixed a wide variety of glitches afflicting the Apiman Manager UI. By Marc Savy (@msavy), Florian Volk (@volkflo).

[manager-api-war]: handle comma-separated lists properly in apiman.properties. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2012

[common-es]: work around ES index creation race condition. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2037

[ui]: browser back button on "all"-pages. By Florian Volk (@volkflo) in https://github.com/apiman/apiman/pull/2005

[manager-api]: client republish and/or unregister when breaking contracts. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2123

[manager-api]: ensures RestExceptionMapper actually prints stack trace. By Marc Savy (@msavy)

[gateway-engine-policies]: check for null request path in URLRewritingPolicy. By Marc Savy (@msavy)

[ui]: add local time to time-restricted-access-policy. By Florian Volk (@volkflo)

[ui]: temporarily disable source maps for production to avoid bloating code. By Marc Savy (@msavy)

[ui]: Ensure modals have correct constructor signature to avoid minification/mangling breaking everything. By Marc Savy (@msavy)

[manager-api-jpa]: include API version in query fetching API definition. By Marc Savy (@msavy)

[manager-api]: PolicyDefinitionTemplate missing #equals and #hashCode By Marc Savy (@msavy)

[manager-api-jpa]: parse stringified numeric filter value into same data type as target field. By Marc Savy (@msavy) in https://github.com/apiman/apiman/pull/2284