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

Incorporated @ivarconr responses to queries about the API. Added some more notes about other documentation opportunities in the comments at the top of the OAS. Added a new section including a sample curl request to getting-started

Browse Source
This commit is contained in:
gazconroy 2020-11-23 15:12:58 +00:00 committed by Ivar Conradi Østhus
parent d4fe56f53b
commit c77f85f60f
2 changed files with 100 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
docs/api/oas/openapi.yaml
View File

@ -1,6 +1,6 @@
# OTHER API DOCS # OTHER API DOCS
# Could do withe an overview. What is it? What does it do? Who is it for? Why would I use this? For a good example, see https://ionicframework.com/docs # Could do withe an overview. What is it? What does it do? Who is it for? Why would I use this? For a good example, see https://ionicframework.com/docs or https://cloud.ibm.com/docs/assistant?topic=assistant-index#index
# Getting started - I have made some tweaks to this but it would be handy to also provide some JS code to make an example API call. PUT /admin​/features​/{featureName} is a good choice (since it has both a Request body and a query parameter) # Getting started - I have made some tweaks to this but it would be handy to also provide some JS code to make an example API call. PUT /admin​/features​/{featureName} is a good choice (since it has both a Request body and a query parameter). Twilio is brilliant example of this kind of stuff. https://www.twilio.com/docs/quickstart
# Status and error codes - It would be useful to generate a simple table listing all status codes. See how Clearbit does it: https://clearbit.com/docs?python#errors # Status and error codes - It would be useful to generate a simple table listing all status codes. See how Clearbit does it: https://clearbit.com/docs?python#errors
# Rate limiting and thresholds - Need to inform people of this even if it's not a 'thing', they will ask. See https://unleash-community.slack.com/archives/CGP2MCHPF/p1603106990003200 See how Twitter API describes their limits: https://developer.twitter.com/en/docs/twitter-api/rate-limits # Rate limiting and thresholds - Need to inform people of this even if it's not a 'thing', they will ask. See https://unleash-community.slack.com/archives/CGP2MCHPF/p1603106990003200 See how Twitter API describes their limits: https://developer.twitter.com/en/docs/twitter-api/rate-limits
# Glossary - Need definitions for, as a start, the project specific stuff: Unleash server, Unleash client, Feature Toggle, Strategy, Variant, Diff. Doesn't need to be massive. For instance, see the Lyft glossary - https://developer.lyft.com/docs/glossary # Glossary - Need definitions for, as a start, the project specific stuff: Unleash server, Unleash client, Feature Toggle, Strategy, Variant, Diff. Doesn't need to be massive. For instance, see the Lyft glossary - https://developer.lyft.com/docs/glossary
@ -8,11 +8,16 @@
# TESTING # TESTING
# QA team test cases. Test code exists but were these based on a list of steps required to produce a result? # QA team test cases. Test code exists but were these based on a list of steps required to produce a result?
# Are there any real-world users of Unleash who are happy to read and test the Open API specification and make suggestions for improvement? Would they be happy to screen-record what they are doing (how they use the API will give invaluable insights)? # Are there any real-world users of Unleash who are happy to read and test the Open API specification and make suggestions for improvement? Would they be happy to screen-record what they are doing (how they use the API will give invaluable insights)?
# Ideally, you'd want developers using Java, Node.js, Go, Ruby, Python and .Net to test
# Could there be a simple sample app that implemented all API calls (using realistic scenarios)? Might just be a consolidated version of the tests/e2e code with some triggers (buttons) and some UI to display outcomes.
# OAS REVIEW # OAS REVIEW
# Move responses to root responses section in components (from schema section) # Move responses to root responses section in components (from schema section)
# Issues with rendering as nested externaldocs from Swagger UI. See GET /admin​/feature-types. Not an issue in other tools (see redoc.html) # Issues with rendering as nested externaldocs from Swagger UI. See GET /admin​/feature-types. Not an issue in other tools (see redoc.html)
# Create output in other non-Swagger styles (as well as Redoc) - such as Readme
# REDOC
# 'Try it out' instructions do not apply since the free version of Redoc has no such feature.
# STYLE # STYLE
# Add style guide MD. UK/US, Newspaper/Movie, Plurals. & # Add style guide MD. UK/US = US, Newspaper/Movie, Plurals. &
# OAS styler - Only use backticks for code samples and API paths. Use bold for schema items and italic for schema item settings # OAS styler - Only use backticks for code samples and API paths. Use bold for schema items and italic for schema item settings
openapi: 3.0.0 openapi: 3.0.0
@ -44,7 +49,7 @@ info:
The following 'endpoints' (such as `GET /admin/metrics/applications`) provide reference documentation for the Unleash REST API. To try out API calls: The following 'endpoints' (such as `GET /admin/metrics/applications`) provide reference documentation for the Unleash REST API. To try out API calls:
1. Expand an endpoint 1. Expand an endpoint
2. Click **Try it out** 2. Click **Try it out**
3. Customise the **Request body** and/or **Parameters**. 3. Customize the **Request body** and/or **Parameters**.
4. Click **Execute**. 4. Click **Execute**.
You will see the cURL request submitted to the API server and the corresponding response. You will see the cURL request submitted to the API server and the corresponding response.
@ -84,7 +89,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -108,7 +113,7 @@ paths:
'400': '400':
description: Bad body request (for example, Feature Toggle name is not unique) description: Bad body request (for example, Feature Toggle name is not unique)
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -137,7 +142,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -167,7 +172,7 @@ paths:
'400': '400':
description: Bad body request (for example 'strategies' is not an array) description: Bad body request (for example 'strategies' is not an array)
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -191,7 +196,7 @@ paths:
'200': '200':
description: Feature Toggle successfully archived description: Feature Toggle successfully archived
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -216,7 +221,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -241,7 +246,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -269,7 +274,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -297,7 +302,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -320,7 +325,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200' $ref: '#/components/schemas/200'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -358,7 +363,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200strategy' $ref: '#/components/schemas/200strategy'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -382,7 +387,7 @@ paths:
'400': '400':
description: Bad body request (for example 'strategies' is not an array) description: Bad body request (for example 'strategies' is not an array)
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -418,7 +423,7 @@ paths:
'200': '200':
description: Strategy successfully updated. description: Strategy successfully updated.
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -458,14 +463,14 @@ paths:
schema: schema:
$ref: '#/components/schemas/200feature' $ref: '#/components/schemas/200feature'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/401' $ref: '#/components/schemas/401'
/admin/metrics/applications: /admin/metrics/applications:
# Documentation says 'You can also specify the query param: strategyName, which will return all applications implementing the given strategy.' However, specifiying this results in a 500 error # Documentation MD says 'You can also specify the query param: strategyName, which will return all applications implementing the given strategy.' However, specifiying this results in a 500 error
get: get:
summary: A list of known applications ('seen' by Unleash in the last two days) summary: A list of known applications ('seen' by Unleash in the last two days)
description: Also has a link for more details. description: Also has a link for more details.
@ -480,13 +485,11 @@ paths:
schema: schema:
$ref: '#/components/schemas/applicationArray' $ref: '#/components/schemas/applicationArray'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/401' $ref: '#/components/schemas/401'
'500':
description: Strategy name not found
'/admin/metrics/applications/{appName}': '/admin/metrics/applications/{appName}':
get: get:
@ -505,7 +508,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200appdetails' $ref: '#/components/schemas/200appdetails'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -528,7 +531,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/applicationArray' $ref: '#/components/schemas/applicationArray'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -539,7 +542,7 @@ paths:
operationId: get-admin-events operationId: get-admin-events
summary: Fetch all changes in the Unleash system summary: Fetch all changes in the Unleash system
description: |- description: |-
Returns one of the five event types: Returns one of the six event types:
- feature-created - feature-created
- feature-updated - feature-updated
- feature-archived - feature-archived
@ -556,7 +559,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200-events' $ref: '#/components/schemas/200-events'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -609,7 +612,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200export' $ref: '#/components/schemas/200export'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -661,7 +664,7 @@ paths:
'200': '200':
description: Successful import. description: Successful import.
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -689,7 +692,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/200featuretype' $ref: '#/components/schemas/200featuretype'
'401': '401':
description: Not authorised description: Not authorized
content: content:
application/json: application/json:
schema: schema:
@ -733,7 +736,7 @@ components:
$ref: '#/components/schemas/featureToggleSchema' $ref: '#/components/schemas/featureToggleSchema'
'401': '401':
description: Not authorised description: Not authorized
type: object type: object
properties: properties:
type: type:
@ -758,7 +761,7 @@ components:
- details - details
properties: properties:
isJoi: isJoi:
description: What is the significance of this flag? description: For internal use by the Unleash developers
type: boolean type: boolean
name: name:
description: Title of error description: Title of error
@ -925,15 +928,16 @@ components:
description: A description of what the application does description: A description of what the application does
type: string type: string
url: url:
description: Link to more information about the application? Relative only? # Question? description: Absolute URL to the actual application
type: string type: string
example: 'https://medium.com/keptn' example: 'http://someapp.internal.url'
color: color:
description: The colour (American English?) of something. Hex code? # Question? description: Deprecated. Do not use
type: string type: string
icon: icon:
description: The icon to use for something. Link? # Question? description: The appkication's icon. Must be one of the [Material Design icon names](https://material.io/resources/icons/?style=baseline)
type: string type: string
example: comment_bank
200appdetails: 200appdetails:
type: object type: object
@ -973,17 +977,17 @@ components:
minLength: 1 minLength: 1
example: 'unleash-client-node:3.4.0' example: 'unleash-client-node:3.4.0'
clientIp: clientIp:
description: The IP address of the system running this instance of the application. What is the prefix on the string? # Question? description: The IP address of the system running this instance of the application
type: string type: string
minLength: 1 minLength: 1
example: '::ffff:127.0.0.1' example: '::ffff:127.0.0.1'
lastSeen: lastSeen:
description: The last time the application accessed Unleash? # Question? description: The last time the application 'talked' to Unleash (sent metrics, registered, fetched feature toggles)
type: string type: string
minLength: 1 minLength: 1
example: '2020-11-14T11:17:24.482Z' example: '2020-11-14T11:17:24.482Z'
createdAt: createdAt:
description: When the application was created? # Question? description: The first time the application registered with Unleash
type: string type: string
minLength: 1 minLength: 1
example: '2020-11-13T16:56:29.279Z' example: '2020-11-13T16:56:29.279Z'
@ -993,11 +997,9 @@ components:
type: object type: object
properties: properties:
self: self:
description: What is this? # Question? description: Deprecated. Do not use
type: string type: string
minLength: 1 minLength: 1
required:
- self
featureToggleTypeSchema: featureToggleTypeSchema:
type: string type: string
@ -1020,7 +1022,7 @@ components:
versionSchema: versionSchema:
type: number type: number
description: What is this? # Question? description: For internal use by the Unleash developers
example: 1 example: 1
featureToggleSchema: featureToggleSchema:
@ -1121,7 +1123,9 @@ components:
minLength: 1 minLength: 1
example: yellow example: yellow
weight: weight:
description: The 'weighting' for the variant. How does Unleash use weighting to determine which variant to use? What is the range? # Question? description: |-
A number between 0 and 1,000.
The client SDK will summarize all variant weights, hash the number and divide the users among them. The distribution will be according to the weight as a fraction of the sum of weight.
type: number type: number
example: 20 example: 20
@ -1142,7 +1146,7 @@ components:
items: items:
properties: properties:
id: id:
description: The event number. Starts at 1? On first run of application version? # Question? description: The event number. All events have a unique id.
type: number type: number
example: 55 example: 55
type: type:
@ -1158,7 +1162,7 @@ components:
minLength: 1 minLength: 1
example: feature-updated example: feature-updated
createdBy: createdBy:
description: Creator of the application? Where is this taken from? # Question? description: The current user's *email* or *username* (taken from the *User* object on the current session)
type: string type: string
minLength: 1 minLength: 1
createdAt: createdAt:
@ -1168,7 +1172,12 @@ components:
data: data:
$ref: '#/components/schemas/featureToggleSchema' $ref: '#/components/schemas/featureToggleSchema'
diffs: diffs:
description: What are diffs? # Question? description: |-
The JSON differences between the current and last version of the Feature Toggle.
(Uses the [deep-diff Node.js module](https://www.npmjs.com/package/deep-diff))
externalDocs:
description: Activation strategies
url: 'https://www.npmjs.com/package/deep-diff#differences'
type: array type: array
items: items:
required: required:
@ -1177,8 +1186,18 @@ components:
- rhs - rhs
properties: properties:
kind: kind:
description: What do these letters signify? What's the full list? # Question? description: |-
The kind of change:
- **N** - a newly-added property or element
- **D** - a property or element was deleted
- **E** - a property or element was edited
- **A** - a change occurred within an array
type: string type: string
enum:
- N
- D
- E
- A
example: E example: E
path: path:
type: array type: array
@ -1187,15 +1206,15 @@ components:
- pathItem - pathItem
properties: properties:
pathItem: pathItem:
description: What's this? # Question? description: The property path (from the left-hand-side root)
type: string type: string
example: enabled example: enabled
lhs: lhs:
description: Left-hand side of something? Sometimes boolean, sometimes an object, sometimes null. What is it? # Question? description: The value on the left-hand-side of the comparison (*undefined* if **kind** is *N*)
type: boolean type: boolean
example: true example: true
rhs: rhs:
description: Left-hand side of something? Sometimes boolean, sometimes an object, sometimes null. What is it? # Question? description: The value on the right-hand-side of the comparison (*undefined* if **kind** is *D*)
type: boolean type: boolean
example: false example: false
@ -1251,12 +1270,15 @@ components:
enum: enum:
- Enables trunk-based development for teams practicing continuous delivery - Enables trunk-based development for teams practicing continuous delivery
- Performs multivariate or A/B testing - Performs multivariate or A/B testing
- Controls operational aspects of the system behaviour # US English? - Controls operational aspects of the system behavior
- Gracefully degrades system functionality - Gracefully degrades system functionality
- Changes the features or product experiences that certain users receive - Changes the features or product experiences that certain users receive
minLength: 1 minLength: 1
lifetimeDays: lifetimeDays:
description: What's this? # Question? description: The number of days this Feature Toggle is intended to be used. This information is used to issue deprecation notices
externalDocs:
description: Feature Toggle types
url: 'https://unleash.github.io/docs/feature_toggle_types'
type: number type: number
example: 40 example: 40

29
docs/getting-started.md
View File

@ -11,7 +11,7 @@ You will need:
- [**PostgreSQL**](https://www.postgresql.org/download/) (version 10 or later) - [**PostgreSQL**](https://www.postgresql.org/download/) (version 10 or later)
- [Create an unleash user and database](./developer-guide.md). - [Create an unleash user and database](./developer-guide.md).
## Start Unleash ## Start Unleash server
Whichever option you choose to start Unleash, you must specify a database URI (it can be set in the environment variable DATABASE_URL). Whichever option you choose to start Unleash, you must specify a database URI (it can be set in the environment variable DATABASE_URL).
@ -22,7 +22,8 @@ Unleash started on http://localhost:4242
### Option one - from a terminal/bash shell ### Option one - from a terminal/bash shell
```npm install unleash-server -g ```
npm install unleash-server -g
unleash -d postgres://unleash_user:password@localhost:5432/unleash -p 4242 unleash -d postgres://unleash_user:password@localhost:5432/unleash -p 4242
``` ```
@ -61,10 +62,30 @@ unleash -d postgres://unleash_user:password@localhost:5432/unleash -p 4242
Launch the [Unleash server Docker image](https://hub.docker.com/r/unleashorg/unleash-server/). Launch the [Unleash server Docker image](https://hub.docker.com/r/unleashorg/unleash-server/).
```sh ```
docker run -d -e DATABASE_URL=postgres://user:pass@10.200.221.11:5432/unleash unleashorg/unleash-server docker run -d -e DATABASE_URL=postgres://user:pass@10.200.221.11:5432/unleash unleashorg/unleash-server
``` ```
<!-- The following doesn't seem to fit the 'remit' of Getting started'. it would be a better fit in the developer section of hte documentatio -->
## Test your server and create a sample API call
Once the Unleash server has started, go to [localhost:4242](http://localhost:4242) in your browser. If you see a list of example feature toggles, try modifying one of them with [curl](https://curl.se/) from a terminal/bash shell:
~~~
curl --location --request PUT 'http://localhost:4242/api/admin/features/Feature.A' --header 'Content-Type: application/json' --data-raw '{\
"name": "Feature.A",\
"description": "Dolor sit amet.",\
"type": "release",\
"enabled": false,\
"stale": false,\
"strategies": [\
{\
"name": "default",\
"parameters": {}\
}\
]\
}'\
~~~
<!-- The following doesn't seem to fit the 'remit' of Getting started'. it would be a better fit in the developer section of the documentation -->
## Unleash server options ## Unleash server options
Available Unleash options include: Available Unleash options include: