Reference

This guide describes configuration options for PingGateway. It is for PingGateway designers, developers, and administrators.

For API specifications, refer to the appropriate Javadoc.

The examples in this guide use some of the following third-party tools:

curl: https://curl.haxx.se
HTTPie: https://httpie.org
jq: https://stedolan.github.io/jq/
keytool: https://docs.oracle.com/en/java/javase/17/docs/specs/man/keytool.html

Reserved routes

By default, PingGateway reserves all paths starting with /openig for administrative use, and only local client applications can access resources exposed under /openig.

PingGateway uses an ApiProtectionFilter to protect reserved routes. By default, the ApiProtectionFilter allows access to reserved routes only from the loopback address. To override this behavior, declare a custom ApiProtectionFilter in the top-level heap. For an example, refer to the CORS filter described in Set up the UMA example.

For information about how to change the base for administrative routes, refer to Change the base location.

Reserved field names

PingGateway reserves all configuration field names that contain only alphanumeric characters.

If you must define your own field names, for example, in custom decorators, use names with dots, ., or dashes, -. Examples include my-decorator and com.example.myDecorator.

Field value conventions

PingGateway configuration uses JSON notation.

This reference uses the following terms when referring to values of configuration object fields:

array: JSON array.

boolean: Either true or false.

certificate: java.security.cert.Certificate instance.

configuration token: Configuration tokens introduce variables into the server configuration. They can take values from Java system properties, environment variables, JSON and Java properties files held in specified directories, and from properties configured in routes. For more information, refer to JSON Evaluation.

duration

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and negative durations are not supported. The following units can be used in durations:

indefinite, infinity, undefined, unlimited: unlimited duration
zero, disabled: zero-length duration
days, day, d: days
hours, hour, h: hours
minutes, minute, min, m: minutes
seconds, second, sec, s: seconds
milliseconds, millisecond, millisec, millis, milli, ms: milliseconds
microseconds, microsecond, microsec, micros, micro, us, µs: microseconds
nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds

enumeration: A collections of constants.

expression: See Expressions.
configuration expression: Expression evaluated at configuration time, when routes are loaded. See Configuration Expressions.
runtime expression: Expression evaluated at runtime, for each request and response. See Runtime Expressions.

instant: An instantaneous point on the timeline, as a Java type. For more information, see Class Instant.

JsonValue: An object (JsonObject), an array (JsonArray), a number (JsonNumber), a string (JsonString), true (JsonValue.TRUE), false (JsonValue.FALSE), or null (JsonValue.NULL).

lvalue-expression: Expression yielding an object whose value is to be set.

Properties whose format is lvalue-expression cannot consume streamed content. They must be written with $ instead of #.

map: An object that maps keys to values. Keys must be unique, and can map to at most one value.

number: JSON number.

object: JSON object where the content depends on the object’s type.

pattern: A regular expression according to the rules for the Java Pattern class.

pattern-template: Template for referencing capturing groups in a pattern by using $n, where n is the index number of the capturing group starting from zero.

For example, if the pattern is \w+\s*=\s*(\w)+, the pattern-template is $1, and the text to match is key = value, the pattern-template yields value.

reference

References an object in the following ways:

An inline configuration object, where the name is optional.
A configuration expression that is a string or contains variable elements that evaluate to a string, where the string is the name of an object declared in the heap.

For example, the following temporaryStorage object takes the value of the system property storage.ref, which must a be string equivalent to the name of an object defined in the heap:
```
{
  "temporaryStorage": "${system['storage.ref']}"
}
```

secret-id: String that references a secret managed by the Commons Secrets API, as described in Secrets.

The secret ID must conform to the following regex pattern: Pattern.compile("(\\.[a-zA-Z0-9])*");

string: JSON string.

url: String representation for a resource available via the Internet. For more information, refer to Uniform Resource Locators (URL).

PingGateway 2024.9

Reference

Reserved routes

Reserved field names

Field value conventions