Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-02-04 00:18:01 +01:00
Code Issues Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
sveisvei 2017-06-28 10:17:48 +02:00
parent 20af766086
commit 38a05f0830
7 changed files with 182 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/api/events-api.md → docs/api/admin/events-api.md
View File

@ -1,6 +1,6 @@
# Events API # 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. Used to fetch all changes in the unleash system.
@ -37,4 +37,4 @@ Defined event types:
} }
] ]
} }
``` ```

47
docs/api/feature-toggles-api.md → docs/api/admin/feature-toggles-api.md
View File

@ -1,29 +1,16 @@
### Fetching Feature Toggles ### Fetching Feature Toggles
`GET: http://unleash.host.com/api/features` `GET: http://unleash.host.com/api/admin/features`
**HEADERS:** This endpoint is the one all admin ui should use to fetch all available feature toggles
* 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 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. current strategy configuration. A feature toggle will have _at least_ one configured strategy.
A strategy will have a `name` and `parameters` map. 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:** **Example response:**
```json ```json
{ {
"version": 1, "version": 2,
"features": [ "features": [
{ {
"name": "Feature.A", "name": "Feature.A",
@ -34,9 +21,7 @@ has the latest response locally.
"name": "default", "name": "default",
"parameters": {} "parameters": {}
} }
], ]
"strategy": "default",
"parameters": {}
}, },
{ {
"name": "Feature.B", "name": "Feature.B",
@ -55,23 +40,17 @@ has the latest response locally.
"percentage": "10" "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 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. 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 ```json
{ {
"name": "Feature.A", "name": "Feature.A",
@ -82,16 +61,14 @@ debug the API and should not be used by the client implementations.
"name": "default", "name": "default",
"parameters": {} "parameters": {}
} }
], ]
"strategy": "default",
"parameters": {}
} }
``` ```
### Create a new Feature Toggle ### Create a new Feature Toggle
`POST: http://unleash.host.com/api/features/` `POST: http://unleash.host.com/api/admin/features/`
**Body:** **Body:**
```json ```json
@ -115,7 +92,7 @@ Returns 200-respose if the feature toggle was created successfully.
### Update a Feature Toggle ### Update a Feature Toggle
`PUT: http://unleash.host.com/api/features/:toggleName` `PUT: http://unleash.host.com/api/admin/features/:toggleName`
**Body:** **Body:**
```json ```json
@ -139,7 +116,7 @@ Returns 200-respose if the feature toggle was updated successfully.
### Archive a Feature Toggle ### 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, 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 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 ### 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 Used to fetch list of archived feature toggles
@ -177,7 +154,7 @@ Used to fetch list of archived feature toggles
### Revive feature toggle ### Revive feature toggle
`POST http://unleash.host.com/api/archive/revive` `POST http://unleash.host.com/api/admin/archive/revive`
**Body:** **Body:**
```json ```json

70
docs/api/metrics-api.md → docs/api/admin/metrics-api.md
View File

@ -1,61 +1,9 @@
# This document describes the client metrics endpoints # This document describes the metrics endpoint for admin ui
### 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
}
}
},
}
```
### Seen-toggles ### 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 This enpoints returns a list of applications and what toogles
unleash has seend for each application. It will only guarantee 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 ### 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 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 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 ### 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 This endpoint returns a list of known applications (seen the last two days) and
a link to follow for more datails. 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", "createdAt": "2016-12-09T14:56:36.730Z",
"links": { "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", "createdAt": "2016-12-09T14:56:36.730Z",
"links": { "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 You can also specify the query param: _strategyName_, which will return all applications
implementing the given strategy. 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 ### 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, This endpoint gives insight into details about a client applcation, such as instances,
strategies implemented and seen toogles. strategies implemented and seen toogles.
@ -239,7 +187,7 @@ strategies implemented and seen toogles.
### Seen applications ### 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. This endpoint gives insight into details about application seen per feature toggle.

6
docs/api/strategies-api.md → docs/api/admin/strategies-api.md
View File

@ -1,7 +1,7 @@
## Strategies API ## Strategies API
### Fetch Strategies ### 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. 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 ### Create strategy
`POST: http://unleash.host.com/api/strategies` `POST: http://unleash.host.com/api/admin/strategies`
**Body** **Body**
@ -81,7 +81,7 @@ Used to create a new Strategy. Name is required and must be unique. It is also r
### Update strategy ### Update strategy
`PUT: http://unleash.host.com/api/strategies/:name` `PUT: http://unleash.host.com/api/admin/strategies/:name`
**Body** **Body**

89
docs/api/client/feature-toggles-api.md Normal file
View File

@ -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": {}
}
```

53
docs/api/client/metrics-api.md Normal file
View File

@ -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
}
}
},
}
```

23
docs/api/index.md
View File

@ -1,14 +1,19 @@
# API Documentation # API Documentation
Version: 1.0 ## Client API
This describes the API provided to unleash-clients.
**Contents:** * [Feature Toggles API](client/feature-toggles-api.md)
* [Metrics API](client/metrics-api.md)
* [Feature Toggles API](feature-toggles-api.md)
* [Strategies API](strategies-api.md)
* [Events API](events-api.md)
* [Metrics API](metrics-api.md)
Others: ## Admin API (internal)
* [Internal Backstage API](internal-backstage-api.ms) 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)