Gearhead
Introduction
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
|
Port |
8014 |
|
Context path |
/config |
|
Host |
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.
Installation
Please refer to the Gearhead Installation.
Usage
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:
-
area Development Basics
-
subpage Configuration Parameters
-
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}/allcurl 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"