Jekyll2026-02-20T23:40:02+00:00https://www.apiman.io/blog/feed.xmlApimanApiman is a flexible open source API Management platform aimed at enterprise users. Combining a rich API design and configuration layer with a fast, modular runtime, it's easy to customise Apiman to do whatever you need with simple Java plugins.Apiman 4 Dev Diary: Hybrid Vert.x Async-Imperative Applications2025-05-12T16:00:00+00:002025-05-12T16:00:00+00:00https://www.apiman.io/blog/apiman-4-vertx

Let’s be honest, whilst async platforms are extremely performant, the programming, debugging, and maintenance of async code is more challenging than imperative programming. The situation has now become yet more nuanced with the arrival of the JVM’s virtual threads.

πŸ’‘ Black Parrot Labs offers comprehensive enterprise support for Apiman.

If you depend on Apiman and want open source to be sustainable, consider working with us.

As the developers and maintainers of the platform, nobody knows Apiman better.

This is adapted from Apiman founder Marc’s post on LinkedIn.

A thought occurred to me while working on Apiman 4 at Black Parrot Labs: even within the same codebase there are often large proportions of code which do not need high performance, as they are only used occasionally (e.g. only used at startup, cached, very occasional use, etc). Wouldn’t it be nice to be able to hybridise your application and have greater architectural flexibility?

With Eclipse Vert.x 4 and 5, in combination with Java’s virtual threads, you can now have that.

Let me give an example:

arch
Figure 1. Simplified Architectural Diagram
snippet
Figure 2. Code Snippet

Let’s say we have a stockbroker service to buy your favourite meme stock. It consists of three components:

  • "Stock Broker" is a used very frequently and has extremely intensive performance requirements. You don’t want to miss out on your opportunity to lose your money very quickly, after all.

  • "Users" and "Permissions" are used much less frequently, but have complex logic which can be burdensome to maintain as "pure" traditional async code.

So, how do we mix and match?

With the latest-and-greatest versions of Vert.x, we can run the Users and Permissions components as 'virtual thread verticles'.

This allows us to call await() on any asynchronous call/future, and block until the response is ready (or an exception thrown). Standard imperative patterns. In the background, Vert.x dispatches the call onto a virtual thread β€” but we don’t need to worry about that.

Given its performance requirements, we implement "Stock Broker" as a standard verticle using our usual asynchronous patterns. When we need data from the Users and Permissions components, we interact over Vert.x’s lightweight message bus, so it is never impacted by the alternative/blocking approach described above for Permissions, Users, etc.

I hope this makes sense; it lets us have the 'best of both worlds' and does not force us to use more challenging techniques on code that does not need it.

You can find more examples on the Vert.x website, and I included an annotated example on the second picture.

So, have any of you created Vert.x applications that are hybrids of virtual thread verticles and standard reactor verticles? I’d love to hear your thoughts!

(Incidentally, the performance of the virtual thread verticles seems excellent, so that probably pushes the needle even higher on which applications justify "real" async).

Thank you to Julien Viet, Julien Ponge, Clement Escoffier, Paulo Lopes, Thomas Segismont et al for your hard work on this. I see your names in the code frequently πŸ˜….

]]>Marc Savymailto:marc@blackparrotlabs.ioLet’s be honest, whilst async platforms are extremely performant, the programming, debugging, and maintenance of async code is more challenging than imperative programming. The situation has now become yet more nuanced with the arrival of the JVM’s virtual threads.Apiman 3.1.2 released!2023-07-07T16:00:00+00:002023-07-07T16:00:00+00:00https://www.apiman.io/blog/apiman-3.1.2.Final

I’m delighted to announce that I have released Apiman 3.1.2.Final.

One particularly useful change I’d like to highlight is that the Vert.x Gateway’s API, when secured by Keycloak, now accepts a list of additionally accepted issuers using allowed-issuers, which is useful for users with more complex auth setups.

{
  // <rest of your config...>

  // Gateway API Authentication. See documentation for further possibilities.
  "auth": {
    "type": "keycloak",
    "config": {
      "flowType": "PASSWORD",
      "requiredRole": "realm:apipublisher",
      "auth-server-url": "...",
      // You can add extra issuers here.
      "allowed-issuers": [ (1)
        "http://keycloak:8080",
        "https://auth.example.com"
      ],
      "realm": "${apiman.auth.realm:-apiman}",
      "resource": "apiman-gateway-api",
      "credentials": {
        "secret": "${apiman.auth.gateway.secret:-password}"
      },
      "ssl-required": "none",
      "disable-trust-manager": true,
      "allow-any-hostname" : true
    }
  }
}
1 You can add extra issuers here; this can be very useful if your setup has internal vs external issuers, and you need to support them all simultaneously.
Need help? Support is available from Apiman’s developers, and helps the project be sustainable. Please be a good open source citizen!

What’s new?

3.1.2.Final

Added

  • [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).

Changed

  • 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).

Removed

Fixed

  • [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).

]]>Marc Savymailto:marc@blackparrotlabs.ioI&#8217;m delighted to announce that I have released Apiman 3.1.2.Final. One particularly useful change I&#8217;d like to highlight is that the Vert.x Gateway&#8217;s API, when secured by Keycloak, now accepts a list of additionally accepted issuers using allowed-issuers, which is useful for users with more complex auth setups.Apiman 3.1.0 released!2023-03-27T19:01:00+00:002023-03-27T19:01:00+00:00https://www.apiman.io/blog/apiman-3.1.1.Final

I’m delighted to announce that I have released Apiman 3.1.0.Final.

Aside from numerous bug fixes and a few interesting new features, this includes a security fix for CVE-2023-28640.

Due to an issue with the release pipeline, we ended up having to cut a 3.1.1.Final release also, but it’s identical to 3.1.0.Final.

Need help? Support is available from Apiman’s developers, and helps the project be sustainable. Please be a good open source citizen!

What’s new?

3.1.0.Final

Added

  • [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).

Changed

  • 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).

Removed

  • [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).

Fixed

  • 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).

Full Changelog: 3.0.0.Final…​3.1.0.Final

]]>Marc Savymailto:marc@blackparrotlabs.ioI&#8217;m delighted to announce that I have released Apiman 3.1.0.Final. Aside from numerous bug fixes and a few interesting new features, this includes a security fix for CVE-2023-28640. Due to an issue with the release pipeline, we ended up having to cut a 3.1.1.Final release also, but it&#8217;s identical to 3.1.0.Final.Potential permissions bypass in Apiman 3.0.0.Final (CVE-2023-28640)2023-03-27T19:00:00+00:002023-03-27T19:00:00+00:00https://www.apiman.io/blog/potential-permissions-bypass-disclosure

A vulnerability in Apiman has been disclosed that you need to be aware of and respond to. It has CVE ID CVE-2023-28640.

Details

Due to a missing permissions check, an attacker with an authenticated Apiman Manager account may be able to gain access to API keys they do not have permission for if they correctly guess the URLs for the non-permitted resource. The URL includes Organisation ID, Client ID, and Client Version of the targeted non-permitted resource, and each of these can have arbitrary values.

While not trivial to exploit, it could be achieved by brute-forcing or guessing common names.

Access to the non-permitted API Keys could allow use of other users' resources without their permission. Whether this is possible in practice depends on the specifics of configuration, such as whether an API key is the only form of security.

Implications

  • A malicious account-holder may be able to get access to an API key they do not have permission for by guessing/fuzzing private URLs in someone else’s organisation.

    • If successful, the key could be used to access APIs that the user does not have permissions for, if the API Key is the only form of security.

  • This vulnerability is only in the Apiman Manager, it does NOT relate directly to the Apiman Gateway.

Actions to take

  • Upgrade to Apiman 3.1.0.Final/3.1.1.Final (or later). The issue is fixed in this version. No special actions should be required when upgrading from 3.0.0.Final.

  • If you are unable to upgrade your version of Apiman, contact to your Apiman support provider for advice/long-term support.

Thanks

I would like to thank @volkflo and @bastiangem for responsibly disclosing this vulnerability.

]]>Marc Savymailto:marc@blackparrotlabs.ioA vulnerability in Apiman has been disclosed that you need to be aware of and respond to. It has CVE ID CVE-2023-28640.Potential permissions bypass in Apiman 1.5.7 through Apiman 2.2.3.Final (CVE-2022-47551)2022-12-19T11:00:00+00:002022-12-19T11:00:00+00:00https://www.apiman.io/blog/permissions-bypass-disclosure

A vulnerability in Apiman has been disclosed that you need to be aware of and respond to. It has CVE ID CVE-2022-47551.

Details

Incorrect default permissions for certain read-only resources in the Apiman 1.5.7.Final through 2.2.3.Final in the Apiman Manager REST API allows a remote authenticated attacker to access information and resources in an Apiman Organizations they are not a member of and/or do not have permissions for.

For example, an attacker may be able to craft an HTTP request to discover APIs that are private to organizations they are not members of, via fuzzing, search, and other similar mechanisms.

If the attacker has sufficient permissions in their own organization, they may also be able to sign up to the private APIs they have discovered by crafting a tailored HTTP request, thereby gaining access to an API Management protected resource that they should have access to.

Implications

  • A malicious account-holder may be able to see information about APIs they do not have permission for.

  • A malicious account-holder may be able to sign up to APIs they do not have permission for.

  • This does NOT relate to the Apiman Gateway.

Actions to take

Broadly, your options are as follows:

  1. Upgrade to Apiman 3.0.0.Final (or later). The issue is fixed in this version.

  2. If you are using an older version of Apiman, contact to your Apiman support provider for advice/long-term support.

How did this happen?

Some read permissions checks from the Apiman Manager REST API were removed as part of a large contribution that Apiman reviewers did not notice.

After making contact with the contributor, the intent of the change was to enable APIs published in an Apiman organization (analogous to a GitHub Organization) to be discovered by an external application β€” but Apiman did not offer a per-API implicit permissions system to achieve this until Apiman 3.0.0.Final, explicit membership of an organization was required.

The contributor removed certain permissions checks as a workaround for the lack of an implicit permissions system without recognising the security implications.

We have established additional processes to catch errors of this type in future.

]]>Marc Savymailto:marc@blackparrotlabs.ioA vulnerability in Apiman has been disclosed that you need to be aware of and respond to. It has CVE ID CVE-2022-47551.Leaping forwards with Apiman 32022-11-30T12:00:00+00:002022-11-30T12:00:00+00:00https://www.apiman.io/blog/apiman-3.0.0.Final

I’m delighted to announce that I have released Apiman 3.0.0.Final.

This is one of the most significant releases in Apiman’s history, with a considerable number of new features and behind-the-scenes improvements.

There is also a new Docker Compose distribution that makes Apiman easier than ever to try out; please give it a go and let us know your thoughts.

Oh, and I’ve created a completely new Jekyll-based website for Apiman that will help me better automate releases β€” I hope you like it!

Feedback and community interaction is critical to the future of the project, so please give us a bit of your time in return for the huge effort that has gone into Apiman 3 πŸ™Œ.

Need help? Support is available from Apiman’s developers, and helps support the project.

What’s new?

apiman 3 out now

I’m glad that you asked. What’s not new!

As of Apiman 3, we are now maintaining a comprehensive changelog to ensure that it’s absolutely clear what we’ve added in a new release. You can see this on our official changelog on GitHub. It’s also a good way to see the latest features and changes that we’re working on as development is in progress.

As there have been a number of significant changes, it’s essential that you to refer to the migration guide.

Without further ado, here’s what’s in Apiman 3:

3.0.0.Final

Thanks

A huge thanks to every company that has worked with Apiman’s main developer via consulting, support, sponsoring features, or other means. Without financial support, Apiman open source will not continue to be developed.

Particular thanks go to the team at Scheer PAS who sponsored a considerable amount of the work that is in the 3.0.0.Final release.

Added

  • [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).

Changed

  • [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.

Removed

  • [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.

Fixed

Full Changelog: 2.2.3.Final…​3.0.0.Final

]]>Marc Savymailto:marc@blackparrotlabs.ioI&#8217;m delighted to announce that I have released Apiman 3.0.0.Final. This is one of the most significant releases in Apiman&#8217;s history, with a considerable number of new features and behind-the-scenes improvements. There is also a new Docker Compose distribution that makes Apiman easier than ever to try out; please give it a go and let us know your thoughts. Oh, and I&#8217;ve created a completely new Jekyll-based website for Apiman that will help me better automate releases β€” I hope you like it!Apiman 2.2.0.Final has been released (updates Keycloak to 15.1.1 &amp; WildFly to 23.0.2.Final)2021-12-25T16:40:00+00:002021-12-25T16:40:00+00:00https://www.apiman.io/blog/apiman-2.2.0.Final-release

Happy Holidays, Apiman fans!

I’ve released Apiman 2.2.0.Final to upgrade Keycloak to 15.1.1 and WildFly to 23.0.2.Final. This is primarily because of another significant security vulnerability that has been disclosed in those platforms.

As we currently bundle an all-in-one Keycloak + Apiman quickstart distribution, we are required to keep our WildFly versions in sync with Keycloak. Hence, WildFly has been bumped to 23.0.2.Final to match Keycloak 15.1.1.

If you are using the Apiman WildFly distribution and customised apiman-standalone.xml you may need to update your configuration file. This is because of changes in the WildFly platform rather than Apiman itself.

Please refer to the Apiman migration guide to understand any changes you may need to make to apiman-standalone.xml (mostly in relation to SSL/TLS).

Most production deployments should unbundle Keycloak and Apiman (both for security and practical reasons).

In a release in the near future, we will stop bundling Keycloak and Apiman in the quickstarts, and instead we will provide a Docker Compose definition that is much more representative of a real-world deployment.

This will also mean Apiman is not forced to stay in sync with Keycloak Server releases. We hope this will be more convenient for Apiman users and the Apiman team.

You can download the latest Apiman at all the usual locations.

All the best for 2022.

If you have questions about this release, please join us on GitHub Discussions.

]]>Marc Savymailto:marc@blackparrotlabs.ioHappy Holidays, Apiman fans! I&#8217;ve released Apiman 2.2.0.Final to upgrade Keycloak to 15.1.1 and WildFly to 23.0.2.Final. This is primarily because of another significant security vulnerability that has been disclosed in those platforms.Apiman 2.1.5.Final has been released - please update if you’re on an old version2021-12-20T14:00:00+00:002021-12-20T14:00:00+00:00https://www.apiman.io/blog/apiman-2.1.5.Final-release

Hi, Apiman fans!

I hope you’re all well, and Season’s Greetings to those of you who celebrate Christmas πŸŽ„.

I’d like to remind Apiman users to consider updating to Apiman 2.1.5 promptly, as it contains fixes for the now well-known log4j2 bugs.

You can download Apiman from all the usual official places: Apiman Downloads or the GitHub release

If you have questions about this release, please join us on GitHub Discussions

]]>Marc Savymailto:marc@blackparrotlabs.ioHi, Apiman fans! I hope you&#8217;re all well, and Season&#8217;s Greetings to those of you who celebrate Christmas πŸŽ„. I&#8217;d like to remind Apiman users to consider updating to Apiman 2.1.5 promptly, as it contains fixes for the now well-known log4j2 bugs.Apiman 2.1.0.Final has been released πŸš€2021-07-27T15:00:00+00:002021-07-27T15:00:00+00:00https://www.apiman.io/blog/apiman-2.1.0.Final-released

I’m very pleased to say that we’ve released Apiman 2.1.0.Final πŸ‘. We’ve splatted a huge number of bugs and made a lot of improvements to stability, performance, and security.

Please consult the migration guide here if you are planning to upgrade from an earlier version if Apiman (especially if you’re using Elasticsearch).

Apiman now can run on any currently released version of Java (assuming the underlying platform can, of course).

You can see everything we’ve fixed in Apiman 2.1.0.Final, and you can download the latest overlays, etc, over on our GitHub repo.

If you prefer the Apiman website, it’s available right away on the downloads page..

As usual, there are some simple Docker quickstart images available: docker run -it -p 8080:8080 -p 8443:8443 apiman/on-wildfly:2.1.0.Final.

A lot of work has gone into this release, and we’re just getting started πŸƒβ€β™‚οΈ.

Let us know how you find Apiman 2.1.0!

Notes

Improvements to logging

If you are a developer writing any kind of code for Apiman (including Apiman plugins or components), you can now instantiate a logger in a more pain-free way than before.

Simply do:

static final IApimanLogger LOGGER = ApimanLoggerFactory.getLogger(klazz.class);

For all distros we ship, we set an appropriate system property to ensure that logging is available and set up as early as possible. But if you implement your own platform or want to override the default logger for a given platform, you can do so by altering the following system property:

apiman.logger-delegate=<name of logging delegate>

Currently the valid values are: log4j2, jboss-logging, slf4j, sout, noop).

You can create your own logger factory if you want, but I’ll save the details of how to do this for a future blog (and update the docs πŸ–Š).

Check out the log4j2 config that ships with the Apiman Vert.x Gateway for an example logger config that uses async logging to improve log performance considerably.

Elasticsearch changes (again).

Apiman 2.0.0.Final had errors in its Manager Elasticsearch schema definition (metrics + gateway was fine). This has been fixed, but there’s no compatible way to auto-migrate, so you’ll need to export and import.

If you’re moving from older versions of Apiman (1.x), the Elasticsearch version used has been upgraded — and that in turn causes incompatibilities (this time it’s not our fault!). Some effort from an administrator is required to upgrade the cluster. Unfortunately upgrading ES clusters has become non-trivial over the years and care is required.

Check out the migration guide for all the details.

Antora-based docs

We’ve worked hard to migrate from GitBook to Antora. GitBook no longer supports Asciidoc. We appreciate their support over the years.

Support Java 11+

Apiman’s codebase now works on all currently released versions of Java. Naturally, depending which platform you’re running on, you may be limited to a particular version (e.g. Wildfly, Tomcat, etc).

Apiman Parent / BOM

We now have a new apiman-parent which allows synchronisation of dependency versions between Apiman projects. This is of particular benefit to apiman-plugins. Plugin authors can use this to harmonise versions and reduce the risk of any incompatibilities.

Maven Wrapper

We’ve added Maven Wrapper. You can use this to ensure you build using the same version of Maven that the Apiman team uses. Simply run your build with ./mvnw instead of mvn in Apiman’s top-level directory.

Tomcat is back

In the 2.0.0.Final release, Tomcat was cut as a main distro. By popular demand, it’s back and has been updated with all the latest-and-greatest Apiman features (e.g. logging with log4j2 by default now).

Swagger/WSDL definitions now show in Apiman exports

In older Apiman releases we mistakenly did not include API definitions in Apiman export files. This meant that when you exported and imported they would vanish.

We’ve fixed this in Apiman 2.1.0.Final, but also provided a migration tool to 'enrich' the JSON exported by older versions with the missing data.

Refer to the migration guide to see how to do this.

Removed some unused bits

We’ve removed Hawkular and some other unused components. Nobody was using them, as far as we were able to ascertain.

UI fixes

A bunch of UI bugs have been fixed that were causing strange glitches in 2.0.0.Final. Some nice shortcut navigation sidebars have been added.

Regressions

Some contributions in 2.0.0.Final caused some issues that have now been fixed.

The most significant one was the Elasticsearch schema causing problems. Unfortunately to fix this you will need to re-import your data. Please refer to the migration guide.

Various issues in the UI that have been fixed (see above).

It was not possible to use ES Metrics and a non-ES API Manager datastore at the same time. This is no longer the case and now works as expected again (e.g. RDBMS + ES works).

Bringing dependencies up to date

Most dependencies have been brought right up to date (except the UI where this isn’t currently essential). This is important for security, performance, and stability - and enabling Apiman to run on newer versions of Java.

Lots more

A large amount of work went into this release. Check out the GitHub release notes and commit log if you’re curious.

]]>Marc Savymailto:marc@blackparrotlabs.ioVersion 1.5 of Apiman is released!2018-08-13T23:00:00+00:002018-08-13T23:00:00+00:00https://www.apiman.io/blog/release-1.5

I’m happy to announce that Apiman 1.5.1.Final is out.

It contains an important new policy feature: the ability to modify policy failures before they are returned to users (even if they are thrown by another policy).

This means that policies such as CORS can add their headers, irrespective of whether the request was successful or not (e.g. due to rate limiting).

Failure Processing

When a policy throws a failure (e.g. rate limit reached), previously this caused an immediate termination that bypassed all other policies. Failure processing was requested in the community to allow policies to modify failures emitted by other policies, such that headers can be set.

To implement this, you simply need to override the default method processFailure in IPolicy:

default void processFailure(PolicyFailure failure, IPolicyContext context, Object config,  IPolicyFailureChain chain) { ... }

Or, if you’re using AbstractMappedPolicy, then you should override doProcessFailure:

protected void doProcessFailure(PolicyFailure failure, IPolicyContext context, C config, IPolicyFailureChain chain) { ... }

For example, in the CORS plugin it simply adds the headers:

@Override
 protected void doProcessFailure(PolicyFailure failure, IPolicyContext context, CorsConfigBean config,
         IPolicyFailureChain chain) {

     CaseInsensitiveStringMultiMap corsHeaders = getResponseHeaders(context);

     if(corsHeaders != EMPTY_MAP) {
         failure.getHeaders().putAll(corsHeaders.toMap());
     }

     chain.doFailure(failure);
 }

Meaning that even if a rate limit is hit, then the headers will still be added.

If you experience any issues, please report them to us via JIRA, GitHub, or the mailing list.

Download 1.5.1.Final

]]>Marc Savymailto:marc@blackparrotlabs.ioI&#8217;m happy to announce that Apiman 1.5.1.Final is out. It contains an important new policy feature: the ability to modify policy failures before they are returned to users (even if they are thrown by another policy). This means that policies such as CORS can add their headers, irrespective of whether the request was successful or not (e.g. due to rate limiting).