Headless Registry

The Apiman headless registry uses an immutable registry to load its configuration from a local or remote JSON file.

Table 1. Available implementations:
Implementation Notes

io.apiman.gateway.engine.vertx.polling.URILoadingRegistry

Recommended. Works well in multi-node setups.
This registry is optimised for the Vert.x gateway implementation. Although it should work for other platforms, it is unlikely to be as performant.

Example

"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.

Required Parameters

Name Type Description

configUri

String

URI to file containing registry configuration. Supports file, http, https.

auth

Enum

Auth mechanism to access resource indicated in configUri.

Allowed Values:

  • NONE: No auth needed.

  • BASIC: BASIC auth.

  • KEYCLOAKOAUTH2: Convenience Keycloak OAuth2 implementation.

  • OAUTH2: Generic OAuth2.

Refer to the subsections for each auth mechanism for respective configuration options.

Default value: NONE.

Authentication

BASIC

Standard BASIC auth with static credentials.

Table 2. Required Parameters
Name Type Description

username

String

A username. Consider using variable substitution.

password

String

A password. Consider using variable substitution.
Example
"config": {
  "configUri": "https://example.org/reg-config.json",
  "auth": "BASIC",
  "username": "MyUsername",
  "password": "${PASSWORD}" (1)
}
1 The password in this example is defined as a variable to be substituted from the config variables, system properties or environment.

Keycloak OAuth2

A convenience Keycloak OAuth2 implementation, allowing you to paste your chosen client configuration from the Keycloak console into the config section.

To retrieve it:

  1. Log into Keycloak (e.g. localhost:8080/auth).

  2. Clients → <Your-Client> → Installation.

  3. Select Keycloak OIDC JSON for Format Option.

  4. Copy the contents and merge into the config selection where indicated below.

The precise configuration you need to provide will vary depending upon your Keycloak setup.

Due to a current limitation in the underlying OAuth2 library you may be required to provide a credentials section to avoid issues. You can change your client type to confidential, or simply provide a dummy credentials section.
Example
"config": {
  "auth": "KeycloakOAuth2",
  "flowType": "password",
  "username": "foo",
  "password": "bar",
  // Start paste & replace your Keycloak config here.
  "realm": "apiman",
  "realm-public-key": "< snip >",
  "auth-server-url": "http://localhost:8080/auth",
  "ssl-required": "none",
  "resource": "apiman-gateway-api",
  "credentials": {
    "secret": "217b725d-7790-47a7-a3fc-5cf31f92a8db"
  }
  // End paste here.
}
Table 3. Required Parameters
Name Type Description

flowType

Enum

The OAuth2 flow for your configuration.

Allowed Values:

  • PASSWORD

  • CLIENT

  • AUTH_CODE

  • AUTH_JWT
Table 4. Optional Parameters
Name Type Description

username

String

A username. Usually only useful if using the password flowType.

password

String

A password. Usually only useful if using the password flowType.

OAuth2

The combination of required parameters and optional parameters will vary considerably depending upon your configuration.
Table 5. Required Parameters
Name Type Description

flowType

Enum

The OAuth2 flow for your configuration.

Allowed Values:

  • PASSWORD

  • CLIENT

  • AUTH_CODE

  • AUTH_JWT

oauthUri

String

The OAuth2 URI.

clientId

String

The OAuth2 client ID.

clientSecret

String

The OAuth2 client secret.
Table 6. Optional Parameters
Name Type Description

site

String

Site URI

publicKey

String

Public key

clientSecret

String

Client secret

username

String

A username. Usually only useful if using the password flowType.

password

String

A password. Usually only useful if using the password flowType.

authorizationPath

String

The authorization path

tokenPath

String

The token path

recovationPath

String

The revocation path

scopeSeparator

String

The introspection path

logoutPath

String

The logout path (OIDC)

useBasicAuthorizationHeader

boolean

Whether to use BASIC auth header (OIDC)

clientSecretParameterName

String

Client secret query parameter name (OIDC)

userInfoPath

String

User info path (OIDC)

introspectionPath

String

User info path (RFC7662)

userAgent

String

User agent

privateKey

String

Private key

Configuration File Format

Configuration of the registry is via a JSON file, the schema for which can be found on GitHub.

Broadly, it consists of:

  • An api array containing your APIs.

  • A clients array containing your Clients.

Example
{
    "apis": [{
        "publicAPI": true,
        "organizationId": "foo",
        "apiId": "foo",
        "version": "foo",
        "endpoint": "http://www.example.org/my-api-uri/",
        "endpointType": "rest", (1)
        "endpointContentType": "json", (2)
        "endpointProperties": {}, (3)
        "parsePayload": false,
        "apiPolicies": [{
            // Plugin's JSON config.
           "policyJsonConfig": "{ \"responseCode\" : \"403\", \"ipList\" : [ \"1.2.3.4\" ] }", (4)
           // Plugin coordinates.
           "policyImpl": "plugin:io.apiman.plugins:apiman-plugins-url-whitelist-policy:3.2.0-SNAPSHOT:war/io.apiman.gateway.engine.policies.IPWhitelistPolicy" (5)
       }]
    }],
    "clients": [{
        "organizationId": "foo",
        "clientId": "fooClient",
        "version": "foo",
        "apiKey": "12345",
        "contracts": [{
            "apiOrgId": "foo",
            "apiId": "foo",
            "apiVersion": "foo",
            "plan": "foo",
            "policies": []
        }]
    }]
}
1 See Endpoint Type.
2 See Endpoint Content Type.
3 See Endpoint Properties.
4 See Policy Config.
5 See Policy Implementation URI.

Endpoint Type

  • rest: Standard RESTful endpoint type.

  • soap: SOAP endpoint type.

Endpoint Content Type

The endpointContentType indicates which format you want apiman’s responses to be in (e.g. error messages).

Endpoint Properties

  • Authorization type (between gateway and backend):

    • Basic Auth: "authorization.type": "basic"

      • Username: "basic-auth.username": "<username>"

      • Password: "basic-auth.password": "<password>"

    • SSL Required?: "basic-auth.requireSSL": "<true|false>"

  • MTLS/MSSL: "authorization.type": "<mtls|ssl>". You should also provide the corresponding SSL certificate settings in the gateway’s config file.

Policy Config

policyJsonConfig is an escaped string containing the policy plugin’s configuration, and must be valid according to the plugin’s schema.

For in-built policies, you can refer to the Policies section of the User Guide to see the available configuration options and samples.

However, for custom policies without explicit documentation a bit more effort may be required:

Each plugin’s schema is defined in source code and bundled within the plugin’s WAR, as defined by the form element in src/main/apiman/policyDefs/<policy-Name>-policyDef.json.

For example, the Simple Header Policy’s simple-header-policyDef.json file points to a JSON schema at schemas/simple-header-policyDef.schema.

In the following sample we’ve built a JSON configuration corresponding to the schema.

Example Simple Header Policy config
{
  "addHeaders": [{
    "headerName": "X-Clacks-Overhead",
    "headerValue": "GNU Terry Pratchett",
    "valueType": "String",
    "applyTo": "Request",
    "overwrite": true,
    "resolvedHeaderValue": "GNU Terry Pratchett"
  }],
  "stripHeaders": []
}

And escaped it, before inserting into policyJsonConfig: [1]

Example Simple Header Policy in policyJsonConfig
"policyJsonConfig": "{\"addHeaders\":[{\"headerName\":\"X-Clacks-Overhead\",\"headerValue\":\"GNU Terry Pratchett\",\"valueType\":\"String\",\"applyTo\":\"Request\",\"overwrite\":true,\"resolvedHeaderValue\":\"GNU Terry Pratchett\"}],\"stripHeaders\":[]}"
For more information, refer to the plugin developer’s guide.

Policy Implementation URI

The policy implementation URI is used by the apiman gateway to look up your plugins. You can find this in the plugin’s policyDef.json file, usually located in src/main/apiman/policyDefs/.

The format is:

plugin:{pluginGroupId}:{pluginArtifactId}:{pluginVersion}:{pluginType}/{fullyQualifiedClassname}

In our example of the Simple Header Policy it’s:

plugin:${project.groupId}:${project.artifactId}:${project.version}:${project.packaging}/io.apiman.plugins.simpleheaderpolicy.SimpleHeaderPolicy

Which then informs us that the URI is:

plugin:io.apiman.plugins:apiman-plugins-simple-header-policy:3.2.0-SNAPSHOT:war/io.apiman.plugins.simpleheaderpolicy.SimpleHeaderPolicy

Note that the classifier is almost certainly war.

For more information, refer to the plugin developer’s guide.
1. You might wonder why JSON is escaped inside JSON. The field name is somewhat of a misnomer, it is intended to be generic and could be XML, YAML, etc.