1
0
mirror of https://github.com/Unleash/unleash.git synced 2024-12-28 00:06:53 +01:00
unleash.unleash/website/docs/reference/api/legacy/unleash/client/features.md

212 lines
6.3 KiB
Markdown
Raw Normal View History

---
title: /api/client/features
---
refactor: move docs into new structure / fix links for SEO (#2416) ## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
2022-11-22 10:05:30 +01:00
> In order to access the client API endpoints you need to identify yourself. Unless you're using the `none` authentication method, you'll need to [create a CLIENT token](/how-to/how-to-create-api-tokens.mdx) and add an Authorization header using the token.
### Fetching Feature Flags {#fetching-feature-toggles}
2016-09-06 21:23:56 +02:00
2017-06-28 10:17:48 +02:00
`GET: http://unleash.host.com/api/client/features`
2016-09-06 21:23:56 +02:00
2016-11-09 12:41:11 +01:00
**HEADERS:**
2018-11-22 11:20:28 +01:00
- UNLEASH-APPNAME: appName
- UNLEASH-INSTANCEID: instanceId
2016-11-09 12:41:11 +01:00
This endpoint is the one all clients should use to fetch all available feature flags from the _unleash-server_. The response returns all active feature flags and their current strategy configuration. A feature flag will have _at least_ one configured strategy. A strategy will have a `name` and `parameters` map.
2016-09-06 21:23:56 +02:00
2018-11-22 11:20:28 +01:00
> _Note:_ Clients should prefer the `strategies` property. Legacy properties (`strategy` & `parameters`) will be kept until **version 2** of the format.
2016-09-06 21:23:56 +02:00
2018-11-22 11:20:28 +01:00
This endpoint should never return anything besides a valid _20X or 304-response_. It will also include an `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 client already has the latest response locally.
2016-09-06 21:23:56 +02:00
**Example response:**
2018-11-22 11:20:28 +01:00
2016-09-06 21:23:56 +02:00
```json
{
"version": 1,
"features": [
{
"name": "Feature.A",
"type": "release",
2016-09-06 21:23:56 +02:00
"enabled": false,
"stale": false,
2016-09-06 21:23:56 +02:00
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"strategy": "default",
"parameters": {}
},
{
"name": "Feature.B",
"type": "killswitch",
2016-09-06 21:23:56 +02:00
"enabled": true,
"stale": false,
2016-09-06 21:23:56 +02:00
"strategies": [
{
"name": "ActiveForUserWithId",
"parameters": {
"userIdList": "123,221,998"
}
},
{
"name": "GradualRolloutRandom",
"parameters": {
"percentage": "10"
}
}
],
"strategy": "ActiveForUserWithId",
"parameters": {
"userIdList": "123,221,998"
}
}
]
}
```
#### Filter feature flags {#filter-feature-toggles}
Supports three params for now
- `tag` - filters for features tagged with tag
- `project` - filters for features belonging to project
- `namePrefix` - filters for features beginning with prefix
For `tag` and `project` performs OR filtering if multiple arguments
To filter for any feature tagged with a `simple` tag with value `taga` or a `simple` tag with value `tagb` use
`GET https://unleash.host.com/api/client/features?tag[]=simple:taga&tag[]simple:tagb`
To filter for any feature belonging to project `myproject` use
`GET https://unleash.host.com/api/client/features?project=myproject`
Response format is the same as `api/client/features`
### Get specific feature flag {#get-specific-feature-toggle}
2017-06-28 10:17:48 +02:00
`GET: http://unleash.host.com/api/client/features/:featureName`
2016-09-06 21:23:56 +02:00
Used to fetch details about a specific feature flag. This is mainly provided to make it easy to debug the API and should not be used by the client implementations.
2016-09-06 21:23:56 +02:00
> _Notice_: You will not get a version property when fetching a specific feature flag by name.
2016-09-06 21:23:56 +02:00
```json
{
"name": "Feature.A",
"type": "release",
2016-09-06 21:23:56 +02:00
"enabled": false,
"stale": false,
2016-09-06 21:23:56 +02:00
"strategies": [
{
"name": "default",
"parameters": {}
}
],
"strategy": "default",
"parameters": {}
}
```
### Strategy Constraints {#strategy-constraints}
:::note Availability
**Version**: `4.16+`
:::
Strategy definitions may also contain a `constraints` property. Strategy constraints is a feature in Unleash which work on context fields, which is defined as part of the [Unleash Context](/reference/unleash-context.md). The purpose is to define a set of rules where all needs to be satisfied in order for the activation strategy to evaluate to true.
**Example response:**
The example shows strategy constraints in action. Constraints is a new field on the strategy-object. It is a list of constraints that need to be satisfied.
In the example `environment` needs to be `production` AND `userId` must be either `123` OR `44` in order for the Unleash Client to evaluate the strategy, which in this scenario is “default” and will always evaluate to true.
```json
{
"type": "release",
"enabled": true,
"stale": false,
"name": "Demo",
"strategies": [
{
"constraints": [
{
"contextName": "environment",
"operator": "IN",
"values": ["production"]
},
{
"contextName": "userId",
"operator": "IN",
"values": ["123", "44"]
}
],
"name": "default",
"parameters": {}
}
]
}
```
- **contextName** - is the name of the field to look up on the unleash context.
- **values** - is a list of values (string).
- **operator** - is the logical action to take on the values Supported operator are:
- **IN** - constraint is satisfied if one of the values in the list matches the value for this context field in the context.
- **NOT_IN** - constraint is satisfied if NONE of the values is the list matches the value for this field in the context.
### Variants {#variants}
All feature flags can also take an array of variants. You can read more about [feature flag variants](/reference/feature-toggle-variants).
```json
{
"version": 1,
"features": [
{
"name": "Demo",
"type": "operational",
"enabled": true,
"stale": false,
"strategies": [
{
"name": "default"
}
],
"variants": [
{
"name": "red",
"weight": 500,
"weightType": "variable",
"payload": {
"type": "string",
"value": "something"
},
"overrides": [
{
"contextName": "userId",
"values": ["123"]
}
]
},
{
"name": "blue",
"weight": 500,
"overrides": [],
"weightType": "variable"
}
]
}
]
}
```
- **payload** - an optional object representing a payload to the variant. Takes two properties if present `type` and `value`.
- **overrides** - an optional array of overrides. If any context field matches any of the the defined overrides it means that the variant should be selected.