. . .



Gearhead service provides functionality to create, update, read and delete configuration properties ( key-value pairs ). You can choose between the different persistence types:

  • File based (default)

  • MongoDB

  • Git based

  • Consul key-value store




Context path




Component interactions

Gearhead is a standalone service which can be used either with or without registration to a discovery service. If you want to use the Gearhead to save and load service configuration properties you need to make sure that it is registered to a discovery service like Consul, so that the other services that interact with Gearhead are able to find the service instance.

For further details read the following sections on this page.


Please refer to the Gearhead Installation.


A) Application specific Service Configuration

To make the communication between the service that wants to save and store its configuration properties and the Gearhead easier, we provide you the apiomat-service-config library. With the help of the java library you are able to define an enum of configuration property definitions inside your service.
The enum just needs to implement a specific Interface which is then used to save and load values for each ApiOmat application.

Additionally the apiomat-service-config-starter helps you with auto-generated REST end points for your Spring Boot Service that provides the save and load functionality for other services.

More detailled information about the usage of the apiomat-service-config library can be found within the following articles:

Save properties

After apiomat-service-config-starter is integrated into your Spring Boot Service, you will be able to save (create or update) configuration property values with the following REST end point:

curl -X PUT http://{HOST}:{PORT}/{SERVICE_CONTEXT_PATH}/apps/{APPNAME}/config -d '{"common.myKey1":true, "common.myKey2":"message"}' -H "Content-Type: application/json" -H "x-apiomat-system: LIVE" -H "Authorization: Basic username:password"

Load properties

To load the save configuration property values of an application use the following REST end points:

curl http://{HOST}:{PORT}/{SERVICE_CONTEXT_PATH}/apps/{APPNAME}/config -H "x-apiomat-system: LIVE" -H "Authorization: Basic username:password"
curl http://{HOST}:{PORT}/{SERVICE_CONTEXT_PATH}/apps/{APPNAME}/config/{KEY}-H "x-apiomat-system: LIVE" -H "Authorization: Basic username:password"

Load properties definition

If you want to load the configuration definition with all its meta data which is used in other components like ApiOmat Dashboard then use the following REST end point:

curl http://{HOST}:{PORT}/{CONTEXT_PATH}/configdefinition -H "x-apiomat-system: LIVE" -H "Authorization: Basic username:password"
curl http://{HOST}:{PORT}/{CONTEXT_PATH}/configdefinition/{KEY} -H "x-apiomat-system: LIVE" -H "Authorization: Basic username:password"

B) Custom Key-Value-Store

If you just want to use the Gearhead as key-value storage you can also directly access the following REST end points. Keep in mind that those key-value pairs won't get integrated automatically into other ApiOmat components like done in option A above!

Create new entry

To create a new key-value entry just use the following POST REST end points (it will fail if the key already exists within the context):

curl -X POST http://localhost:8014/config/v1/{name} -d '{"custom1":12345.6, "custom2":"text"}' -H "Content-Type: application/json"
curl -X POST http://localhost:8014/config/v1/{name}/{label} -d '{"custom1":12345.6, "custom2":"text"}' -H "Content-Type: application/json"

The path parameter name is used as configuration context (on file-based persistence this would be the filename) and the path parameter label is used as sub category (on file-based persistence this is an additional subdirectory).

Update entries

To save a key-value entry (update or create) use the following PUT REST end points:

curl -X PUT http://localhost:8014/config/v1/{name} -d '{"custom1":12345.6, "custom2":"text"}' -H "Content-Type: application/json"
curl -X PUT http://localhost:8014/config/v1/{name}/{label} -d '{"custom1":12345.6, "custom2":"text"}' -H "Content-Type: application/json"

Read entries

To read all key-value entries use one of the first two end points and to read one specific entry use the last two end points:

curl http://localhost:8014/config/v1/{name}
curl http://localhost:8014/config/v1/{name}/{label}/all
curl http://localhost:8014/config/v1/{name}/{key}
curl http://localhost:8014/config/v1/{name}/{label}/{key}

Delete entries

To delete key-value pairs just send a list of keys to the following end points:

curl -X DELETE http://localhost:8014/config/v1/{name} -d '["custom1","custom2"]' -H "Content-Type: application/json"
curl -X DELETE http://localhost:8014/config/v1/{name}/{label} -d '["custom1","custom2"]' -H "Content-Type: application/json"