The toggle guru (Japanese for toggle).
Contributions are welcome!
See contribution documentation.
The management API is exposed via a REST interface over http(s).
All management API endpoints requires authentication with an api key. For this, provide host header with a valid api key in your http requests:
Authorization: api-key [your-api-key]
with curl, the syntax to add the proper header is
curl -H "Authorization: api-key ???" https://your-endpoint.example.com/auditlog
In the service configuration, auth.api-keys
must contain an array of objects with fields
name
and hash
. The hash must be created with BCrypt, see e.g.
the test configuration.
The management API tries to help on how to proceed when a problem occurs (due to e.g. lack of authentication or a malformed request).
Http method and route: GET /auditlog
Payload format: no payload required
Response format:
[
{ "id": "toguru-demo-toggle",
"event": "toggle created",
"name": "Toguru demo toggle",
"description": "Toguru demo toggle",
"tags": { "team": "Toguru team" },
"meta": {
"time": "2016-12-20T15:05:46.705Z",
"epoch": 1482246346705,
"user": "toguru-team"
}
}
]
This endpoint is used by the Toguru clients to retrieve the current state of all toggles.
Http method and route: GET /togglestate
Payload format: no payload required
Response format:
[
{ "id": "toguru-demo-toggle",
"tags": { "team": "Toguru team" },
"activations": [
{ "rollout": { "percentage": 20 },
"attributes": {
"hair": [ "black", "white" ]
}
}
]
}
]
Http method and route: POST /toggle
Payload format:
{ "name": "Toguru demo toggle",
"description": "Toguru demo toggle",
"tags": { "team": "Toguru team" }
}
All fields are mandatory. The JSON object under tags may have arbitrary fields, and must have string fields only. An empty tags map is allowed.
Response format:
{ "status":"Ok", "id": "toguru-demo-toggle" }
curl example:
curl -XPOST https://your-endpoint.example.com/toggle \
-d '{"name":"Toguru demo toggle","description":"Toguru demo toggle","tags":{"team":"Toguru team"}}'
Http method and route: DELETE /toggle/:id
Payload format: no payload required
Response format:
{ "status": "Ok"}
curl example:
curl -XDELETE https://your-endpoint.example.com/toggle/toguru-demo-toggle
Http method and route: GET /toggle/:id
Payload format: no payload required
Response format:
{ "id": "toguru-demo-toggle",
"name": "Toguru demo toggle",
"description": "Toguru demo toggle",
"tags": { "team": "Toguru team" },
"activations": [
{ "attributes": { "hair": [ "black", "white" ] },
"rollout": { "percentage": 20 }
] }
curl example:
curl https://your-endpoint.example.com/toggle/toguru-demo-toggle
To activate a toggle, you need to create a toggle activation that defines the rollout percentage and additional attribute-based constraints that the ClientInfo must have in order for the toggle to switched on.
Http method and route: POST /toggle/:id/activations
Payload format:
{ "rollout": { "percentage": 20 },
"attributes": { "culture": [ "de-DE", "DE"] , ... } }
Rollout and attributes are both optional, fields in attributes can be defined as needed, values of attribute fields can be strings or array of strings.
Response format:
{ "status": "Ok", "index": 0 }
curl example:
curl -XPOST https://your-endpoint.example.com/toggle/toguru-demo-toggle/activations \
-d '{ "rollout": { "percentage": 20 }, "attributes": { "culture": "de-DE" } }'
Http method and route: PUT /toggle/:id/activations/0
Payload format:
{ "rollout": { "percentage": 20 }, "attributes": { "hair": "black" } }
Rollout and attributes are both optional, fields in attributes can be defined as needed, values of attribute fields can be strings or array of strings.
Response format:
{ "status": "Ok"}
curl example:
curl -XPUT https://your-endpoint.example.com/toggle/toguru-demo-toggle/activations/0 \
-d '{ "rollout": { "percentage": 20 }, "attributes": { "hair": ["black", "white"] } }'
Disabling a toggle is done by deleting its activation.
Http method and route: DELETE /toggle/:id/activations/0
Payload format: no payload required
Response format:
{ "status": "Ok"}
curl example:
curl -XDELETE https://your-endpoint.example.com/toggle/toguru-demo-toggle/activations/0
When starting a toguru server, the toggle state endpoint will initially return an outdated toggle state. This is because the ToggleState actor needs to replay all toggle state changes before it is serving the recent toggle state.
In order to prevent serving this stale state, the configuration setting
toggleState.initializeOnStartup
is set to true
by default. This setting
also causes the health check to fail until the toggle state endpoint is fully
initialized.
To switch both behaviours off, set toggleState.initializeOnStartup
to false
.
- Scout24/toguru-scala-client: Scala client for this toggling service
- Scout24/toguru-panel: UI panel for toggle management
See the LICENSE file for license rights and limitations (MIT).