Define your ApiOmat application specific configuration parameters

It is possible to define ApiOmat application and system related configuration for your service, for which values can be dynamically accessed and changed within your service at runtime. The configuration parameters you define within your service will also be accessible through the Dashboard, or via REST calls. A configuration parameter is defined by adding an enumeration value to the generated ConfigDefinition class, implementing IServiceConfigDefinition, of your service (com.apiomat.microservice.[service_name].config.[service_name]ConfigDefinition.java):Java

The enumeration provides several data types, an example value, a title and a description for a specific configuration parameter. You can modify the display order of the parameters in the service configuration screen of the dashboard, as shown below, via the order field. For configurations of type Enum, you can provide some comma-separated hint values (e.g. "1, 2, 3").

Access your configuration parameters from the Dashboard

To see the service configuration in the Dashboard, simply open the context menu of the service and click on "Configure":

The configuration dialog will open, you can set the value of the configuration parameter there:

The value will be saved as a String, Boolean, Long or Double depending on its type (default is String).

Store and retrieve your configuration parameters values within your service logic

The values of your configuration parameters are stored per application and system in the configuration service Gearhead.

You can get the current value of a configuration parameter per application in the service code by calling the readValue method of the ServiceConfigRequester class, for which a bean is auto-configured in your Spring context thanks to the apiomat-service-config-starter library:Java

The last parameter configDefinition corresponds to the enum definition Object of the specific configuration parameter value you want to retrieve. The readValue method returned type will depend on the data type you specified in the configuration enum definition.

• If no value is saved in the configuration server, the default value will be returned.

• If you specified the type Boolean, the method will try to parse the values "true" and "1" to true, and "false" and "0" to false.

• If you specified the type Number, the value will be returned as an instance of java.lang.Number. We recommend working with this return type and not casting the value to e.g. an Integer to avoid ClassCastExceptions.
  

It is also possible to retrieve multiple values at once:Java

The last parameter configDefinitionList corresponds to the list of enum definitions of the configuration parameters for which you want to retrieve the values. This will return a map with the enum definition as the key and the configuration parameter value as the map value. If a value cannot not be found, its defined default value will be returned (as with readValue above).

You also have the possibility to directly save a value within your service logic by calling either the saveValue or createValue method:
Java

The createValue should be used if you want the method to fail when a value already exists. If you want to update a value (or save a value that does not exist yet) ,you should use the saveValue method. These methods return a boolean value (true on success, else false).

It is also possible to store multiple values at once:Java

As described above, createValues should be used for protected saving, which will fail if any of the configuration parameters you want to update already have a value stored. If you want to update all the values (inclusive creation on non-existence) you should use the saveValues method. The last parameter configValuesMap corresponds to a map in which you should give the enum definition you want to store a value for as key, and the value you want to store as value.

Retrieve your service specific ApiOmat parameter definitions via REST

To make it easier for Spring Boot service to use the configuration parameters features of ApiOmat, we provide a specific library: apiomat-service-config-starter.

The library provides an auto-configured Spring Web controller component ServiceConfigProviderController that defines endpoints to request service configuration definitions. This controller and its endpoints are automatically registered to the spring context of any service which has apiomat-service-config-starter as a dependency, and which provide a Bean of type IServiceConfigProvider.

The automatically available endpoints to retrieve the application configuration definitions are:

• GET /configdefinition - returns a list of IServiceAppConfigDefinition

• GET /configdefinition/{key} - returns a single IServiceAppConfigDefinition via the given parameter key, a String that will be used as path parameter.

A bean of ServiceConfigProvider, which will be used by the ServiceConfigProviderController, is defined in your generated service configuration with the custom Enum implementation of IServiceAppConfigDefinition, e.g. for the generated service MyService with the custom Enum implementation MyServiceConfigDefinition :

Thanks to the IServiceConfigProvider bean defined in your configuration and the apiomat-service-config-starter dependency in your service pom.xml, the definition can then be retrieved by calling:

• GET http://{SERVICE_HOST}:{SERVICE_PORT}/{CONTEXT_PATH}/configdefinition to retrieve the entire service application configuration definition list.

• GET http://{SERVICE_HOST}:{SERVICE_PORT}/{CONTEXT_PATH}/configdefinition/{KEY} to retrieve a single service application configuration definition.

Retrieve and store service specific ApiOmat parameter values via REST

The auto-configured Spring Web controller component ServiceConfigProviderController also provides endpoints to request service configuration values.

The automatically available endpoints to retrieve or store the application configuration values are the following :

• PUT /apps/{appName}/config - save one or more configuration values per ApiOmat application

• GET /apps/{appName}/config - get all configuration values of the service saved for the given ApiOmat application

• GET /apps/{appName}/config/{key} - get a specific configuration value of the service saved for the given ApiOmat application

As described above, to access these endpoints a bean of ServiceConfigProvider, which will be used by the ServiceConfigProviderController, is defined in your generated service configuration with the custom Enum implementation of IServiceAppConfigDefinition, e.g. for the generated service MyService with the custom Enum implementation MyServiceConfigDefinition:

Thanks to the IServiceConfigProvider bean defined in your configuration and the apiomat-service-config-starter dependency in your service pom.xml, the parameters values can then be saved or retrieved by calling:

• PUT http://{HOST}:{PORT}/{CONTEXT_PATH}/apps/{APPNAME}/config to save the given configuration values to a specific application.

• GET http://{HOST}:{PORT}/{CONTEXT_PATH}/apps/{APPNAME}/config to load all the configuration values from a specific application.

• GET http://{HOST}:{PORT}/{CONTEXT_PATH}/apps/{APPNAME}/config/{key} to load a single configuration value from a specific application.

For a full curl request example including needed headers see Gearhead usage.