General Apiman Manager Configuration

Logging In

Once Apiman is running, you should be able to log in to the API Manager by pointing your browser at the following URL:

http://localhost:8080/apimanui/

or

https://localhost:8443/apimanui/

You may log in with credentials admin/admin123!

We strongly advise that you immediately change the Keycloak admin user’s password, as well as the admin user found in the apiman realm!

You can do that by navigating to localhost:8080/auth/admin/.

General Configuration

Of course Apiman is made up of a number of different components, many of which can be configured to use various implementations and/or providers. When downloading and installing Apiman, the default distribution includes reasonable default values for all options. This section details these options and explains the default values.

Configuration Properties

All of the Apiman WARs share a common configuration file called apiman.properties, which can be found in standalone/configuration. This file therefore contains configuration settings for all three applications (API Manager, API Manager UI, API Gateway).

Please refer to the apiman.properties file itself, as well as this document, for more information on each property’s purpose and possible values.

If you are running a non-Servlet gateway implementation (e.g. Vert.x), then you should refer to that gateway’s configuration documentation to understand how to configure it.

API Manager Database

The API Manager, by default, is a typical CDI application and uses JPA/Hibernate to persist its data. The JPA layer requires a data source to connect to a supported database. When running in WildFly this datasource is made available by deploying the following file:

standalone/deployments/apiman-ds.xml

Out of the box this data source is usually a simple H2 configuration, but you can (of course) change it to support whatever database you desire.

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <datasource jndi-name="jdbc/ApiManDT" pool-name="apiman-manager-api" enabled="true"
    use-java-context="true">
    <connection-url>jdbc:h2:${jboss.server.data.dir}${/}h2${/}apiman-manager-api;MVCC=true</connection-url>
    <driver>h2</driver>
    <security>
      <user-name>sa</user-name>
    </security>
  </datasource>
</datasources>

The project comes with DDLs for MySQL and PostgreSQL, to hopefully make it easy to switch away from H2. Note that switching databases also requires a change to the apiman.properties file. The following should be changed to appropriate values for your database:

apiman.hibernate.dialect=io.apiman.manager.api.jpa.ApimanMySQL5Dialect
apiman.hibernate.hbm2ddl.auto=validate

Note that the following dialects are available:

  • io.apiman.manager.api.jpa.ApimanH2Dialect

  • io.apiman.manager.api.jpa.ApimanMySQL5Dialect

  • io.apiman.manager.api.jpa.ApimanOracle12Dialect

  • io.apiman.manager.api.jpa.ApimanPostgreSQLDialect

You can, of course, set the hbm2ddl property to "update" so that hibernate automatically creates the database structure when it starts up. Additional DDLs for various databases can be found in apiman/ddls/.

Custom API Catalog

The API Manager has a feature where users can import APIs from a globally configured API Catalog. By default, Apiman comes with a community catalog that contains a set of common public APIs such as Flickr and Netflix. When deploying Apiman into an enterprise setting, it is often useful to replace the community API Catalog with something that lists out the internal APIs available within the enterprise.

High Level Overview

  1. Describe your enterprise APIs as Apiman API Catalog JSON

  2. Make your enterprise API Catalog available in URL form

  3. Point Apiman at your enterprise API Catalog

Create a Custom Enterprise API Catalog JSON

The first thing you will need to do is express all of your enterprise APIs as a JSON file. The format of the JSON file is specific to Apiman. You can find an example of the format here:

github.com/apiman/apiman-api-catalog/blob/master/catalog.json

Make Your Enterprise API Catalog Available

Now that you have a custom JSON based API Catalog, you need to make it available at a URL accessible to the API Manager. This can either be done by stashing it in some web server location so you have an http based URL, or you can store it locally on the API Manager server so as to have a valid file based URL.

Point Apiman at Your Enterprise API Catalog

The last step is to make Apiman aware of your custom API Catalog file. The catalog is configured in the apiman.properties file via these properties:

apiman-manager.api-catalog.type=io.apiman.manager.api.core.catalog.JsonApiCatalog
apiman-manager.api-catalog.catalog-url=https://cdn.rawgit.com/apiman/apiman-api-catalog/1.5.7.Final/catalog.json

Simply change the URL defined by the apiman-manager.api-catalog.catalog-url property and you’re good to go!

For even more customization, you can actually implement your own API Catalog java class. This approach will allow you to find your APIs in whatever location they happen to be (e.g. a database, registry, etc). Please see the Developer Guide for more information on how to create a truly custom API Catalog.

Custom Plugin Registry

The API Manager uses a plugin registry to show admin users a list of available plugins that can be installed. Apiman comes with an official plugin registry that shows a list of the standard Apiman plugins. If your enterprise implements a large number of custom policies, you may find it useful to replace the standard registry with one that includes your custom plugins in the list.

High Level Overview

  1. Describe your enterprise plugins in a registry JSON file

  2. Make your enterprise plugin registry available in URL form

  3. Point Apiman at your enterprise plugin registry

Create a Custom Enterprise Plugin Registry JSON

The first thing you will need to do is express all of your enterprise plugins as a JSON file. The format of the JSON file is specific to Apiman. You can find an example of the format here:

github.com/apiman/apiman-plugin-registry/blob/master/registry.json

Make Your Enterprise Plugin Registry Available

Now that you have a custom JSON based plugin registry, you need to make it available at a URL accessible to the API Manager. This can either be done by stashing it in some web server location so you have an http based URL, or you can store it locally on the API Manager server so as to have a valid file based URL.

Point Apiman at Your Enterprise Plugin Registry

The last step is to make Apiman aware of your custom plugin registry file. The registry is configured in the apiman.properties file via the following property:

apiman-manager.plugins.registries=https://cdn.rawgit.com/apiman/apiman-plugin-registry/1.5.7.Final/registry.json

The value of this property is a comma-separated list of URLs. Each URL in the list should point to a valid plugin registry JSON file. To include your enterprise plugins in the list, simply add the URL to your plugin registry to the end of the existing list.

Property Replacement in Policy Config

It is often useful to externalize certain information that varies from one deployment environment to another. For example, you may have an LDAP server for authentication, but you have one in the Test deployment environment and a different one in Production. Rather than configure your Apiman policies differently in each environment (to match the actual LDAP connection info) you can externalize those settings into system properties or environment variables. Once that is done, you can refer to those properties/variables in your Apiman policy configuration.

High Level Overview

  1. Externalize values into system properties or environment variables

  2. Reference a system property or environment variable in a policy

Externalize Values

Depending on your deployment strategy, how you do this may vary. If you are using WildFly, for example, you can set system properties in the standalone.xml file or by passing them in via -D parameters on startup (not recommended). For more information, see:

docs.wildfly.org/20/Admin_Guide.html#General_configuration_concepts

Describing all approaches to setting system properties and environment variables is out of scope for this document.

Reference a System Property or Environment Variable

Once you have some values externalized into system properties or environment variables, you can reference them easily in your Apiman policies. All you need to do is use the Ant style syntax to refer to your externalized values, like this:

${MY_ENVIRONMENT_VARIABLE}

A variable of this style can be used in any Apiman policy configuration field. The variables are resolved when the policy configuration is first loaded, and then cached. To change a value, you must restart your server.

When resolving variables, if there is an environment variable with the same name as a system property, the value of the system property will be used.