Apiman Vert.x Gateway

The apiman Vert.x distro is our premier gateway offering and should provide the best performance characteristics of any of our platforms.

The implementation is the apiman gateway only, and hence is normally paired with the Manager and UI from the Servlet edition (e.g. WildFly, EAP, Jetty, etc), but it can be run headless for specific workloads.

There are a few different common configuration examples shipped with the Vert.x distro; they are outlined in more detail below, but you can customise your configurations however you see fit by mixing and matching components.

Download & launch

Download the latest apiman Vert.x distro from apiman.io downloads page, or:

wget https://downloads.jboss.org/apiman/1.3.1.Final/apiman-distro-vertx-1.3.1.Final.zip

Extract the archive and execute it with:

unzip apiman-distro-vertx-1.3.1.Final
cd apiman-distro-vertx-1.3.1.Final
./apiman-gateway.sh --conf configs/conf-es.json

Where config-es.json is your configuration file. Refer to the config and its annotations for additional detail.

If the gateway has started successfully then you should see console output similar to:

$ ./apiman-gateway.sh --conf configs/conf-es.json
[INFO ] ... InitVerticle - Starting verticle: INITIALISER. UUID: 7c577980-716c-4bb9-93a8-e517b0ae15a5.INITIALISER.
[INFO ] ... InitVerticle - Will deploy 1 of type API
[INFO ] ... InitVerticle - Will deploy 8 of type HTTP
[INFO ] ... ApiVerticle - Starting verticle: API. UUID: aad6996f-16e0-4a87-baa7-5fc4843c76bf.API.
[INFO ] ... HttpGatewayVerticle - Starting verticle: HTTP. UUID: effa81a3-fa74-4bd6-813f-8ad09c86344b.HTTP.
[INFO ] ... HttpGatewayVerticle - Starting verticle: HTTP. UUID: 09827a46-6d41-4ab1-aef2-0d152e31fe15.HTTP.
[INFO ] ... InitVerticle - Will deploy 0 of type HTTPS
[WARN ] ... ApiVerticle - API is running in plaintext mode. Enable SSL in config for production deployments.
[INFO ] ... InitVerticle - Successfully deployed all verticles
[INFO ] ... InitVerticle - Gateway API port: 8081
[INFO ] ... VertxIsolatedDeployer - Succeeded in deploying verticle

Test your gateway

To quickly verify whether the installation is working, try [1]:

$ curl -v 'http://apimanager:[email protected]:8081/system/status'
You must alter the default passwords and enable SSL for production deployments, otherwise your system will be at risk.

Version information can be displayed with the version flag [2]:

$ ./apiman-gateway.sh --version
[INFO ] ApimanVersionCommand - Apiman 1.3.0.Final
[INFO ] ApimanVersionCommand - Vert.x 3.4.0


Some example configurations ship with the distro, aiming to provide sensible defaults.

Refer to the comments within the shipped configuration files, the configuration guide and the registries & components documentation for further detail.


The Elasticsearch config conf-es.json comes pre-configured with Elasticsearch components.

Alter the variables.apiman.es configuration variables to match your Elasticsearch setup.

You can either use the Elasticsearch instance bundled with the Apiman Manager, or run your own cluster (which is the preferred option for production).

You can optionally set a username and password; this is only useful if you are using a security service like Elasticsearch Shield to enable authentication.

"variables": {
  "apiman": {
    "es": {
      "protocol": "http",
      "host": "localhost",
      "port": 19200, (1)
      "username": null, // Optional
      "password": null, // Optional
      "timeout": 10000
  1. The default port of a standalone ES cluster is typically 9200. The ES bundled with the apiman Manager is set to 19200 by default to avoid port clashes.

Refer to the Elasticsearch registries & components documentation for a complete list of configuration options.

Headless Elasticsearch

The Apiman Headless Elasticsearch config conf-headless-es.json uses an immutable registry to load its configuration from a local or remote JSON file. All other components (e.g. metrics, rate-limiting, etc) use Elasticsearch.

First, alter your configuration as detailed in the Elasticsearch section.

Then, modify the registry.config section of the config:

"registry": {
  "class": "io.apiman.gateway.engine.vertx.polling.URILoadingRegistry",
  "config": {
    "configUri": "file:///path/to/my/json/reg-config.json", (1)
    "auth": "NONE" (2)
  1. A file, http or https URI to a JSON file containing the registry configuration, as detailed in Configuration File Format.

  2. Authentication method to retrieve the file, as detailed in Authentication.

Refer to the Elasticsearch headless registry documentation for a complete list of configuration options..

3scale Immutable

The 3scale immutable registry config conf-3scale-immutable-es.json uses a 3scale backend to derive its configuration, rather than the Apiman manager. It works with both 3scale SaaS and 3scale on-prem.

This config is immutable; configuration is loaded only once at startup, and a restart is required to reflect new changes.

This initial 3scale integration is on the apiman side only; applying policies requires a separate JSON overlay file to be provided and is not yet stored in the 3scale backend.

  1. Alter your configuration as detailed in the Elasticsearch section. This is used for for apiman metrics, distributed state, caching, etc.

  2. Refer to the 3scale registry documentation to understand the mandatory and other configuration options available for the 3scale registry.

  3. Optionally, you can provide a JSON overlay to apply apiman policies to your 3scale APIs. In future we hope to provide a cohesive integration of this feature.

  4. After loading your APIs will be available at: /services/<API SYSTEM NAME>. For example, http://localhost:8081/services/mycoolapi.

"registry": {
  "class": "io.apiman.gateway.engine.threescale.ThreeScaleImmutableRegistry",
  "config": {
    "accessToken": "<YOUR ACCESS TOKEN>", (1)
    "apiEndpoint": "https://<YOUR-USERNAME>-admin.3scale.net/", (2)
    "backendEndpoint": "https://su1.3scale.net:443", (3)
    "policyConfig": {
      "overlayUri": "file:///my/overlay.json", (4)
      // For HTTP(S), BASIC and OAuth2 are supported. Refer to docs for more info.
      "auth": "NONE" (5)
    "defaultOrgName": "${3scale.defaultOrgName}",
    "defaultVersion": "${3scale.defaultVersion}"
  1. 3scale access token.

  2. API endpoint, if SaaS is usually the https://<username>-admin.3scale.net provided.

  3. 3scale backend to do auth and reports. By default this is the SaaS endpoint, but if you are deploying on-prem you should alter this.

  4. Apiman policy overlay file, can be HTTP, HTTPS or File.

  5. If using HTTP/S auth can be provided.

1. If a non-default host, port and protocol, otherwise alter the command accordingly.
2. When a SNAPSHOT version is used, further information is displayed to identify the precise commit used to build the project and understand the state of the git repo. For example: Apiman 1.3.1-SNAPSHOT apiman-1.3.0.Final-3-g1b9ebf5 2017-05-08 12:15:53.

results matching ""

    No results matching ""