diff --git a/docs/api/events-api.md b/docs/api/admin/events-api.md similarity index 93% rename from docs/api/events-api.md rename to docs/api/admin/events-api.md index 86fac06321..aece9ffdb1 100644 --- a/docs/api/events-api.md +++ b/docs/api/admin/events-api.md @@ -1,6 +1,6 @@ # Events API -`GET: http://unleash.host.com/api/events` +`GET: http://unleash.host.com/api/admin/events` Used to fetch all changes in the unleash system. @@ -37,4 +37,4 @@ Defined event types: } ] } -``` \ No newline at end of file +``` diff --git a/docs/api/feature-toggles-api.md b/docs/api/admin/feature-toggles-api.md similarity index 68% rename from docs/api/feature-toggles-api.md rename to docs/api/admin/feature-toggles-api.md index db4cae6360..744983474b 100644 --- a/docs/api/feature-toggles-api.md +++ b/docs/api/admin/feature-toggles-api.md @@ -1,29 +1,16 @@ ### Fetching Feature Toggles -`GET: http://unleash.host.com/api/features` +`GET: http://unleash.host.com/api/admin/features` -**HEADERS:** - -* UNLEASH-APPNAME: appName -* UNLEASH-INSTANCEID: instanceId - -This endpoint is the one all clients should use to fetch all available feature toggles +This endpoint is the one all admin ui should use to fetch all available feature toggles from the _unleash-server_. The response returns all active feature toggles and their current strategy configuration. A feature toggle will have _at least_ one configured strategy. A strategy will have a `name` and `parameters` map. -> _Note:_ Clients should perfer the `strategies` property. -> Legacy properties (`strategy` & `parameters`) will be kept until **version 2** of the format. - -This endpoint should never return anything besides a valid *20X or 304-response*. It will also -include a `Etag`-header. The value of this header can be used by clients as the value of -the `If-None-Match`-header in the request to prevent a data transfer if the clients already -has the latest response locally. - **Example response:** ```json { - "version": 1, + "version": 2, "features": [ { "name": "Feature.A", @@ -34,9 +21,7 @@ has the latest response locally. "name": "default", "parameters": {} } - ], - "strategy": "default", - "parameters": {} + ] }, { "name": "Feature.B", @@ -55,23 +40,17 @@ has the latest response locally. "percentage": "10" } } - ], - "strategy": "ActiveForUserWithId", - "parameters": { - "userIdList": "123,221,998" - } + ] } ] } ``` -`GET: http://unleash.host.com/api/features/:featureName` +`GET: http://unleash.host.com/api/admin/features/:featureName` Used to fetch details about a specific featureToggle. This is mostly provded to make it easy to debug the API and should not be used by the client implementations. -> _Notice_: You will not get a version property when fetching a specific feature toggle by name. - ```json { "name": "Feature.A", @@ -82,16 +61,14 @@ debug the API and should not be used by the client implementations. "name": "default", "parameters": {} } - ], - "strategy": "default", - "parameters": {} + ] } ``` ### Create a new Feature Toggle -`POST: http://unleash.host.com/api/features/` +`POST: http://unleash.host.com/api/admin/features/` **Body:** ```json @@ -115,7 +92,7 @@ Returns 200-respose if the feature toggle was created successfully. ### Update a Feature Toggle -`PUT: http://unleash.host.com/api/features/:toggleName` +`PUT: http://unleash.host.com/api/admin/features/:toggleName` **Body:** ```json @@ -139,7 +116,7 @@ Returns 200-respose if the feature toggle was updated successfully. ### Archive a Feature Toggle -`DELETE: http://unleash.host.com/api/features/:toggleName` +`DELETE: http://unleash.host.com/api/admin/features/:toggleName` Used to archive a feature toggle. A feature toggle can never be totally be deleted, but can be archived. This is a design decision to make sure that a old feature @@ -149,7 +126,7 @@ toggle suddenly reappears becuase someone else re-using the same name. ### Fetch archived toggles -`GET http://unleash.host.com/api/archive/features` +`GET http://unleash.host.com/api/admin/archive/features` Used to fetch list of archived feature toggles @@ -177,7 +154,7 @@ Used to fetch list of archived feature toggles ### Revive feature toggle -`POST http://unleash.host.com/api/archive/revive` +`POST http://unleash.host.com/api/admin/archive/revive` **Body:** ```json diff --git a/docs/api/metrics-api.md b/docs/api/admin/metrics-api.md similarity index 69% rename from docs/api/metrics-api.md rename to docs/api/admin/metrics-api.md index 97060e4bcc..f9e1e316e1 100644 --- a/docs/api/metrics-api.md +++ b/docs/api/admin/metrics-api.md @@ -1,61 +1,9 @@ -# This document describes the client metrics endpoints - -### Client registration - -`POST: http://unleash.host.com/api/client/register` - -Register a client instance with the unleash server. The client should send all fields specified. - -```json -{ - "appName": "appName", - "instanceId": "instanceId", - "strategies": ["default", "some-strategy-1"], - "started": "2016-11-03T07:16:43.572Z", - "interval": 10000, -} -``` - - -**Fields:** - -* **appName** - Name of the application seen by unleash-server -* **instanceId** - Instance id for this application (typically hostname, podId or similar) -* **strategies** - List of strategies implemented by this application -* **started** - When this client started. Should be reported as UTC time. -* **interval** - At wich interval will this client be expected to send metrics? - -### Send metrics - -`POST http://unleash.host.com/api/client/metrics` - -Register a metrics payload with a timed bucket. - -```json -{ - "appName": "appName", - "instanceId": "instanceId", - "bucket": { - "start": "2016-11-03T07:16:43.572Z", - "stop": "2016-11-03T07:16:53.572Z", - "toggles": { - "toggle-name-1": { - "yes": 123, - "no": 321 - }, - "toggle-name-2": { - "yes": 111, - "no": 0 - } - } - }, -} -``` +# This document describes the metrics endpoint for admin ui ### Seen-toggles -`GET http://unleash.host.com/api/client/seen-toggles` +`GET http://unleash.host.com/api/admin/seen-toggles` This enpoints returns a list of applications and what toogles unleash has seend for each application. It will only guarantee @@ -96,7 +44,7 @@ will in most cases remember seen-toggles for applications longer ### Feature-Toggles metrics -`GET http://unleash.host.com/api/client/metrics/feature-toggles` +`GET http://unleash.host.com/api/admin/metrics/feature-toggles` This endpoint gives _last minute_ and _last hour_ metrics for all active toggles. This is based on metrics reported by client applications. Yes is the number of times a given feature toggle @@ -147,7 +95,7 @@ was evaluated to enabled in a client applcation, and no is the number it avaluat ### Applications -`GET http://unleash.host.com/api/client/applications` +`GET http://unleash.host.com/api/admin/applications` This endpoint returns a list of known applications (seen the last two days) and a link to follow for more datails. @@ -165,7 +113,7 @@ a link to follow for more datails. ], "createdAt": "2016-12-09T14:56:36.730Z", "links": { - "appDetails": "/api/client/applications/another" + "appDetails": "/api/admin/applications/another" } }, { @@ -177,7 +125,7 @@ a link to follow for more datails. ], "createdAt": "2016-12-09T14:56:36.730Z", "links": { - "appDetails": "/api/client/applications/bow" + "appDetails": "/api/admin/applications/bow" } } ] @@ -188,14 +136,14 @@ a link to follow for more datails. You can also specify the query param: _strategyName_, which will return all applications implementing the given strategy. -`GET http://unleash.host.com/api/client/applications?strategyName=someStrategyName` +`GET http://unleash.host.com/api/admin/applications?strategyName=someStrategyName` ### Application Details -`GET http://unleash.host.com/api/client/applications/:appName` +`GET http://unleash.host.com/api/admin/applications/:appName` This endpoint gives insight into details about a client applcation, such as instances, strategies implemented and seen toogles. @@ -239,7 +187,7 @@ strategies implemented and seen toogles. ### Seen applications -`GET http://unleash.host.com/api//client/seen-apps` +`GET http://unleash.host.com/api/admin/seen-apps` This endpoint gives insight into details about application seen per feature toggle. diff --git a/docs/api/strategies-api.md b/docs/api/admin/strategies-api.md similarity index 94% rename from docs/api/strategies-api.md rename to docs/api/admin/strategies-api.md index 862e024973..3ba64e5952 100644 --- a/docs/api/strategies-api.md +++ b/docs/api/admin/strategies-api.md @@ -1,7 +1,7 @@ ## Strategies API ### Fetch Strategies -`GET: http://unleash.host.com/api/strategies` +`GET: http://unleash.host.com/api/admin/strategies` Used to fetch all defined strategies and their defined paramters. @@ -51,7 +51,7 @@ Used to fetch all defined strategies and their defined paramters. ### Create strategy -`POST: http://unleash.host.com/api/strategies` +`POST: http://unleash.host.com/api/admin/strategies` **Body** @@ -81,7 +81,7 @@ Used to create a new Strategy. Name is required and must be unique. It is also r ### Update strategy -`PUT: http://unleash.host.com/api/strategies/:name` +`PUT: http://unleash.host.com/api/admin/strategies/:name` **Body** diff --git a/docs/api/client/feature-toggles-api.md b/docs/api/client/feature-toggles-api.md new file mode 100644 index 0000000000..43664ea9bb --- /dev/null +++ b/docs/api/client/feature-toggles-api.md @@ -0,0 +1,89 @@ +### Fetching Feature Toggles + +`GET: http://unleash.host.com/api/client/features` + +**HEADERS:** + +* UNLEASH-APPNAME: appName +* UNLEASH-INSTANCEID: instanceId + +This endpoint is the one all clients should use to fetch all available feature toggles +from the _unleash-server_. The response returns all active feature toggles and their +current strategy configuration. A feature toggle will have _at least_ one configured strategy. +A strategy will have a `name` and `parameters` map. + +> _Note:_ Clients should perfer the `strategies` property. +> Legacy properties (`strategy` & `parameters`) will be kept until **version 2** of the format. + +This endpoint should never return anything besides a valid *20X or 304-response*. It will also +include a `Etag`-header. The value of this header can be used by clients as the value of +the `If-None-Match`-header in the request to prevent a data transfer if the clients already +has the latest response locally. + +**Example response:** +```json +{ + "version": 1, + "features": [ + { + "name": "Feature.A", + "description": "lorem ipsum", + "enabled": false, + "strategies": [ + { + "name": "default", + "parameters": {} + } + ], + "strategy": "default", + "parameters": {} + }, + { + "name": "Feature.B", + "description": "lorem ipsum", + "enabled": true, + "strategies": [ + { + "name": "ActiveForUserWithId", + "parameters": { + "userIdList": "123,221,998" + } + }, + { + "name": "GradualRolloutRandom", + "parameters": { + "percentage": "10" + } + } + ], + "strategy": "ActiveForUserWithId", + "parameters": { + "userIdList": "123,221,998" + } + } + ] +} +``` + +`GET: http://unleash.host.com/api/client/features/:featureName` + +Used to fetch details about a specific featureToggle. This is mostly provded to make it easy to +debug the API and should not be used by the client implementations. + +> _Notice_: You will not get a version property when fetching a specific feature toggle by name. + +```json +{ + "name": "Feature.A", + "description": "lorem ipsum..", + "enabled": false, + "strategies": [ + { + "name": "default", + "parameters": {} + } + ], + "strategy": "default", + "parameters": {} +} +``` diff --git a/docs/api/client/metrics-api.md b/docs/api/client/metrics-api.md new file mode 100644 index 0000000000..86af96598d --- /dev/null +++ b/docs/api/client/metrics-api.md @@ -0,0 +1,53 @@ +# This document describes the client metrics endpoints + +### Client registration + +`POST: http://unleash.host.com/api/client/register` + +Register a client instance with the unleash server. The client should send all fields specified. + +```json +{ + "appName": "appName", + "instanceId": "instanceId", + "strategies": ["default", "some-strategy-1"], + "started": "2016-11-03T07:16:43.572Z", + "interval": 10000, +} +``` + + +**Fields:** + +* **appName** - Name of the application seen by unleash-server +* **instanceId** - Instance id for this application (typically hostname, podId or similar) +* **strategies** - List of strategies implemented by this application +* **started** - When this client started. Should be reported as UTC time. +* **interval** - At wich interval will this client be expected to send metrics? + +### Send metrics + +`POST http://unleash.host.com/api/client/metrics` + +Register a metrics payload with a timed bucket. + +```json +{ + "appName": "appName", + "instanceId": "instanceId", + "bucket": { + "start": "2016-11-03T07:16:43.572Z", + "stop": "2016-11-03T07:16:53.572Z", + "toggles": { + "toggle-name-1": { + "yes": 123, + "no": 321 + }, + "toggle-name-2": { + "yes": 111, + "no": 0 + } + } + }, +} +``` diff --git a/docs/api/index.md b/docs/api/index.md index c0d2388a31..b727aa7f39 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,14 +1,19 @@ # API Documentation -Version: 1.0 +## Client API +This describes the API provided to unleash-clients. -**Contents:** - -* [Feature Toggles API](feature-toggles-api.md) -* [Strategies API](strategies-api.md) -* [Events API](events-api.md) -* [Metrics API](metrics-api.md) +* [Feature Toggles API](client/feature-toggles-api.md) +* [Metrics API](client/metrics-api.md) -Others: -* [Internal Backstage API](internal-backstage-api.ms) \ No newline at end of file +## Admin API (internal) +The interal API used by the Admin UI (unleash-frontend): + +* [Feature Toggles API](admin/feature-toggles-api.md) +* [Strategies API](admin/strategies-api.md) +* [Events API](admin/events-api.md) +* [Metrics API](admin/metrics-api.md) + +## System API's +* [Internal Backstage API](internal-backstage-api.ms)