# simpleStrategySchema works (and may be correct for some responses) # strategySchema can't render in Swagger UI. use simple for now # Add questions list # Check for $ref substitutions - see the 'required' items # Need to define variants schema openapi: 3.0.0 servers: - description: Local host. url: 'http://localhost:4242/api' tags: - name: Archive description: Handling Feature Toggle archiving and un-archiving - name: Events description: Idientifying events on the Unleash server - name: Feature toggles description: Accessing feature toggles - name: Feature types description: Details of the five Unleash Feature Toggle types - name: Import and export description: Importing and exporting feature toggles and strategies - name: Metrics description: Determining usage of feature toggles and applications - name: Strategies description: Accessing and updating strategies info: title: Unleash API description: Unleash is a open source feature flag and toggle system for all your applications and services. version: 3.5.6 contact: name: The Unleash team url: 'https://unleash.github.io/' # email: some_email@gmail.com externalDocs: description: Unleash documentation url: 'https://unleash.github.io/docs/getting_started' paths: /admin/features: get: summary: Fetches all feature toggles from the Unleash server. description: | 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:** To only return one Feature Toggle, add the Feature Toggle name as a suffix to the request. For example: `GET [Your host]/api/admin/features/featureX`. It is not possible to add this parameter as a *Try it out* option due to restrictions in the [Open API Specification](https://swagger.io/docs/specification/describing-parameters/), (that is, *optional* path variables cannot be created). externalDocs: description: Activation strategies url: 'https://unleash.github.io/docs/activation_strategy' operationId: getFeatures tags: - Feature toggles responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '401': description: Not authorised content: application/json: schema: $ref: '#/components/schemas/401' post: description: Create a new Feature Toggle tags: - Feature toggles operationId: createFeatureToggle requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/newFeatureToggle' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '409': description: Feature Toggle name is not unique content: application/json: schema: $ref: '#/components/schemas/409' summary: Create a Feature Toggle '/admin/features/{featureName}': put: summary: Update a Feature Toggle description: Update a Feature Toggle. operationId: featureName tags: - Feature toggles parameters: - $ref: '#/components/parameters/featureNamePath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/updateFeatureToggle' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' delete: summary: Archive a Feature Toggle. description: | Feature toggles can only be archived - they cannot be deleted. If an old Feature Toggle *re-appears*, this is because someone else has created a new one with the same name. operationId: archiveFeatureToggle tags: - Feature toggles parameters: - $ref: '#/components/parameters/featureNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '/admin/features/{featureName}/toggle/on': post: summary: Enable a Feature Toggle. description: '*featureName* must match an existing Feature Toggle.' operationId: enableFeatureToggle tags: - Feature toggles parameters: - $ref: '#/components/parameters/featureNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '/admin/features/{featureName}/toggle/off': post: summary: Disable a Feature Toggle. description: '*featureName* must match an existing Feature Toggle.' operationId: disableFeatureToggle tags: - Feature toggles parameters: - $ref: '#/components/parameters/featureNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '/admin/features/{featureName}/stale/on': post: summary: Mark a Feature Toggle as 'stale' (deprecated). description: '*featureName* must match an existing Feature Toggle.' externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' operationId: markFeatureToggleStale tags: - Feature toggles parameters: - $ref: '#/components/parameters/featureNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '/admin/features/{featureName}/stale/off': post: summary: Mark a Feature Toggle as active. description: '*featureName* must match an existing Feature Toggle.' externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' operationId: markFeatureToggleActive tags: - Feature toggles parameters: - $ref: '#/components/parameters/featureNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '409': description: Feature Toggle name is not unique. content: application/json: schema: $ref: '#/components/schemas/409' /admin/archive/features: get: summary: List all the archived feature toggles on the Unleash server description: Archived feature toggles are those that have been previously deleted operationId: fetchArchivedToggles tags: - Archive responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' '/admin/archive/revive/{featureName}': post: summary: Un-archive a Feature Toggle description: The Feature Toggle had been previously deleted operationId: reviveFeatureToggle tags: - Archive parameters: - $ref: '#/components/parameters/featureNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200' /admin/strategies: get: summary: Fetch all strategies and their parameters. description: Fetch all strategies and their parameters. operationId: getStrategies tags: - Strategies responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200strategy' post: summary: Create Strategy description: Create Strategy operationId: createStrategy tags: - Strategies requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/createStrategy' responses: '201': description: Strategy successfully added '/admin/strategies/{strategyName}': put: summary: Update Strategy description: | Use to update a Strategy definition. *name* and *strategyName* must match and must also match an existing Strategy name. **Caution:** It can be dangerous to change a Strategy (as the implementation also might need to be changed). operationId: updateStrategy tags: - Strategies parameters: - $ref: '#/components/parameters/strategyNamePath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/createStrategy' responses: '200': description: Strategy successfully updated. /admin/metrics/seen-toggles: get: summary: Returns a list of applications and the feature toggles that Unleash has 'seen' for each application. description: 'It is only guaranteed that feature toggles reported by client applications within the last hour will be returned. However, in most cases, earlier reported feature toggles will also be returned.' operationId: seenToggles tags: - Metrics responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200seen' /admin/metrics/feature-toggles: get: summary: Gives 'last minute' and 'last hour' metrics for all active toggles (based on what was reported by the client applications). description: | - **Yes** is the number of times a given feature toggle was enabled in a client applcation - **No** is the number of times it was disabled. operationId: featureToggles tags: - Metrics responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200feature' /admin/metrics/applications: get: summary: A list of known applications ('seen' by Unleash in the last two days) description: Also has a link for more details. operationId: getApplications tags: - Metrics parameters: - $ref: '#/components/parameters/strategyQuery' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200application' '/admin/metrics/applications/{appName}': get: summary: Details about a client application. description: 'Details include things such as instances, strategies implemented and seen feature toggles.' operationId: getApplicationDetails tags: - Metrics parameters: - $ref: '#/components/parameters/appNamePath' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200appdetails' /admin/metrics/seen-apps: get: summary: Details about application seen per Feature Toggle. description: Details about application seen per Feature Toggle. operationId: seenApps tags: - Metrics responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/200seenapps' /admin/events: get: summary: Fetch all changes in the Unleash system tags: - Events responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/200-events' operationId: get-admin-events description: |- Returns one of the five event types: - feature-created - feature-updated - feature-archived - feature-revived - strategy-created - strategy-deleted /admin/state/export: get: summary: Export feature toggles and strategies tags: - Import and export responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/200export' operationId: get-admin-state-export parameters: - schema: type: string in: query name: format description: | Choose export format, either json or yaml. json is the default - schema: type: boolean in: query name: download description: Export the data as a file? Default is false - schema: type: boolean in: query name: featureToggles description: Include feature toggles in the export? Default is true - schema: type: boolean in: query name: strategies description: Include strategies in the export? Default is true description: Exports a list of feature toggles and/or strategies in either JSON or YAML format. /admin/state/import: post: summary: Import feature toggles and strategies operationId: post-admin-state-import tags: - Import and export responses: '200': description: Successful import. description: Upload the data, in JSON or YAML format, in the POST body. What schema must the import file adopt? Same as the export 200 response? parameters: - schema: type: boolean default: 'false' in: query name: drop description: Be careful using this in production environments. Set to true if you want the to remove all strategies and feature toggles from the datebase before import. Default is false. - schema: type: boolean default: 'true' in: query name: keep description: Set to true if you want keep all existing feature toggles and strategies as is; only the missing feature toggles and strategies will be inserted from the import data. Default is true. requestBody: content: multipart/form-data: schema: type: object properties: fileName: type: string format: binary /admin/feature-types: get: summary: Fetch the list of Unleash feature types description: |- - release - experiment - ops - killswitch - permission operationId: get-admin-feature-types tags: - Feature types responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/200featuretype' components: parameters: strategyQuery: name: strategyName in: query description: (Optional). Return all applications implementing the specified Strategy. Must match an existing Strategy name. schema: type: string featureNamePath: name: featureName required: true in: path description: Must match an existing Feature Toggle. schema: type: string strategyNamePath: name: strategyName required: true in: path description: Must match an existing Strategy name. schema: type: string appNamePath: name: appName required: true in: path description: Must match an existing application name. schema: type: string schemas: '200': title: Successful response type: object properties: version: type: number features: type: array uniqueItems: true minItems: 1 items: properties: name: description: Feature Toggle name type: string minLength: 1 example: featureX description: description: What the Feature Toggle does type: string minLength: 1 type: description: One of the five types of Feature Toggle externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' type: string minLength: 1 example: release enabled: description: Is the Feature Toggle enabled? type: boolean stale: description: Is the Feature Toggle 'stale' (deprecated)? type: boolean strategies: $ref: '#/components/schemas/simpleStrategySchema' variants: type: array uniqueItems: true minItems: 1 items: required: - name - weight properties: name: type: string minLength: 1 weight: type: number '401': description: Not authorised type: object properties: type: type: string minLength: 1 path: type: string minLength: 1 message: type: string minLength: 1 required: - type - path - message '409': type: object properties: isJoi: type: boolean name: type: string minLength: 1 details: type: array uniqueItems: true minItems: 1 items: required: - message properties: message: type: string minLength: 1 required: - isJoi - name - details 200strategy: description: Successful. type: object required: - version - strategies properties: version: type: number example: 1 strategies: $ref: '#/components/schemas/simpleStrategySchema' newFeatureToggle: type: object required: - name - description - enabled - stale - strategies properties: name: description: Feature Toggle name must be unique. type: string minLength: 1 example: FeatureA description: description: What the Feature Toggle does type: string minLength: 1 example: Toggles FeatureA on and off type: type: string description: '*type* is optional. If not defined, it defaults to `release`' externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' enum: - release - experiment - ops - killswitch - permission minLength: 1 example: release enabled: type: boolean example: false stale: description: Is the Feature Toggle deprecated (stale)? type: boolean example: false strategies: $ref: '#/components/schemas/simpleStrategySchema' updateFeatureToggle: type: object properties: description: type: string minLength: 1 example: Toggles FeatureB on and off type: type: string minLength: 1 description: '*type* is optional. If not defined, it defaults to `release`' example: release enabled: type: boolean example: false stale: type: boolean example: false strategies: $ref: '#/components/schemas/simpleStrategySchema' variants: {} createdAt: type: string minLength: 1 required: - name - description - enabled - stale - strategies - variants createStrategy: type: object properties: name: type: string minLength: 1 example: gradualRollout description: type: string minLength: 1 example: Gradual rollout to logged in users parameters: type: array uniqueItems: true minItems: 1 items: required: - name - type - description - required properties: name: type: string minLength: 1 example: percentage type: type: string minLength: 1 example: percentage description: type: string minLength: 1 example: What percent of users should the new Feature Toggle be active for? required: type: boolean required: - name - description - parameters 200seen: type: array description: '' minItems: 1 uniqueItems: true items: type: object required: - appName - seenToggles - metricsCount properties: appName: type: string minLength: 1 seenToggles: type: array items: properties: {} metricsCount: type: number 200feature: description: | - **lastHour** - how many times a Feature Toggle was accessed in the last hour. - **lastMinute** - how many times a Feature Toggle was accessed in the last minute. type: array minItems: 1 uniqueItems: true items: type: object required: - appName - seenToggles properties: appName: type: string enum: - lastHour - lastMinute minLength: 1 example: lastHour seenToggles: type: object required: - yesno - metricsCount properties: yesno: type: string enum: - 'yes' - 'no' metricsCount: type: number 200application: type: object required: - applications properties: applications: type: array uniqueItems: true minItems: 1 items: required: - appName - createdAt - updatedAt - strategies properties: appName: description: Application name type: string example: my-application createdAt: description: Date and time when the application was initially created type: string example: '2016-12-09T14:56:36.730Z' updatedAt: description: Date and time when the application was last updated type: string example: '2020-11-14T09:55:23.653Z' description: description: A description of what the application does type: string strategies: description: A description of what the application does type: string url: description: Link to more information about the application? Relative only? type: string example: 'https://medium.com/keptn' color: description: The colour (American English?) of something. Hex code? type: string icon: description: The icon to use for something. Link? type: string 200appdetails: type: object required: - appName - instances - strategies - seenToggles properties: appName: description: Application name type: string minLength: 1 example: my-application createdAt: description: Date and time when the application was initially created type: string example: '2016-12-09T14:56:36.730Z' description: description: A description of what the application does type: string url: description: Link to more information about the application? Relative only? type: string example: 'https://medium.com/keptn' color: description: The colour (American English?) of something. Hex code? type: string icon: description: The icon to use for something. Link? type: string strategies: $ref: '#/components/schemas/simpleStrategySchema' instances: type: object required: - appName - instanceId - sdkVersion - clientIp - lastSeen - createdAt properties: appName: description: Application name type: string minLength: 1 example: my-application instanceId: description: The name of the system running the application type: string minLength: 1 example: generated-732038-17080 sdkVersion: description: The version of the Unleash client SDK running the application type: string minLength: 1 example: 'unleash-client-node:3.4.0' clientIp: description: The IP address of the system running this instance of the application. What is the prefix on the string? type: string minLength: 1 example: '::ffff:127.0.0.1' lastSeen: description: The last time the application accessed Unleash? type: string minLength: 1 example: '2020-11-14T11:17:24.482Z' createdAt: description: When the application was created? type: string minLength: 1 example: '2020-11-13T16:56:29.279Z' seenToggles: type: array uniqueItems: true minItems: 1 items: required: - name - type - enabled - stale - createdAt properties: name: description: Name of the Feature Toggle type: string minLength: 1 example: FeatureX description: description: What the Feature Toggle does type: string type: description: One of the five types of Feature Toggle type: string externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' minLength: 1 example: release enabled: description: Is the Feature Toggle enabled? type: boolean stale: description: Is the Feature Toggle type: boolean strategies: $ref: '#/components/schemas/strategySchema' variants: description: What is this? type: string createdAt: description: Date and time when the application was initially created type: string minLength: 1 example: '2020-11-09T15:25:59.517Z' links: type: object properties: self: description: What is this? type: string minLength: 1 required: - self 200seenapps: type: object properties: my-toggle: type: array items: required: - appName - createdAt - updatedAt - description - url - icon properties: appName: description: Appplication name type: string minLength: 1 example: my-application createdAt: description: Date and time when the application was initially created type: string minLength: 1 example: '2016-12-09T14:56:36.730Z' updatedAt: description: Date and time when the application was last updated type: string minLength: 1 example: '2020-11-14T09:55:23.653Z' description: description: A description of what the application does type: string minLength: 1 strategies: $ref: '#/components/schemas/simpleStrategySchema' url: description: Link to more information about the application? Relative only? type: string minLength: 1 example: 'https://medium.com/keptn' color: description: The colour (American English?) of something. Hex code? type: string icon: description: The icon to use for something. Link? type: string minLength: 1 strategySchema: type: array properties: name: description: Name of the Strategy type: string minLength: 1 example: default editable: type: boolean description: description: What the Strategy is type: string example: Default on/off strategy. parameters: type: array items: required: - parameter properties: parameter: type: object required: - name - type properties: name: description: The name of the parameter type: string example: groupId type: description: The type of the parameter type: string example: string description: description: What the parameter does type: string example: Define activation groups to allow you to correlate across feature toggles. required: description: Is this a required parameter? type: boolean simpleStrategySchema: type: object required: - appName - parameterName properties: appName: description: Application name type: string minLength: 1 example: demo-app strategies: type: array items: required: - strategyName properties: parameterName: description: Name of Strategy's parameter type: string example: extra 200-events: type: object properties: version: description: Version number of what? type: number example: 1 events: type: array required: - id - type - createdBy - createdAt uniqueItems: true minItems: 1 items: properties: id: description: The event number. Starts at 1? On first run of application version? type: number example: 55 type: description: One of the five event types type: string enum: - feature-created - feature-updated - feature-archived - feature-revived - strategy-created - strategy-deleted minLength: 1 example: feature-updated createdBy: description: Creator of the application? Where is this taken from? type: string minLength: 1 createdAt: description: Date and time when the application was initially created type: string example: '2016-12-09T14:56:36.730Z' data: type: object required: - name - description - type - enabled - stale - strategies - createdAt properties: name: description: Feature Toggle name . type: string minLength: 1 example: FeatureA description: description: What the Feature Toggle does type: string minLength: 1 example: Toggles FeatureA on and off type: type: string description: '*type* is optional. If not defined, it defaults to `release`' externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' enum: - release - experiment - ops - killswitch - permission minLength: 1 example: release enabled: type: boolean example: false stale: description: Is the Feature Toggle deprecated (stale)? type: boolean example: false strategies: $ref: '#/components/schemas/simpleStrategySchema' variants: {} createdAt: description: Date and time when the Feature Toggle was created? type: string minLength: 1 example: '2020-11-09T13:51:08.949Z' diffs: description: What are diffs? I don't think this part of the schema is correct type: array items: required: - kind - lhs - rhs properties: kind: type: string example: E path: type: array items: required: - pathItem properties: pathItem: description: What's this? type: string example: enabled lhs: description: Left-hand side of something? type: boolean rhs: description: Left-hand side of something? type: boolean 200export: type: object required: - version - features - strategies properties: version: description: Version number of what? type: number example: 1 features: type: array uniqueItems: true minItems: 1 items: required: - name - description - type - enabled - stale - createdAt properties: name: description: Feature Toggle name . type: string minLength: 1 example: FeatureA description: description: What the Feature Toggle does type: string minLength: 1 example: Toggles FeatureA on and off type: type: string description: '*type* is optional. If not defined, it defaults to `release`' externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' enum: - release - experiment - ops - killswitch - permission minLength: 1 example: release enabled: type: boolean example: false stale: description: Is the Feature Toggle deprecated (stale)? type: boolean example: false strategies: $ref: '#/components/schemas/simpleStrategySchema' variants: {} createdAt: type: string minLength: 1 strategies: $ref: '#/components/schemas/simpleStrategySchema' 200featuretype: type: object properties: version: description: A version number of something? type: number example: 1 types: type: array uniqueItems: true minItems: 1 items: required: - id - name - description - lifetimeDays properties: id: description: The *id* string for the Feature Toggle type externalDocs: description: Feature Toggle types url: 'https://unleash.github.io/docs/feature_toggle_types' type: string minLength: 1 example: release name: description: The title of the Feature Toggle type type: string enum: - Release - Experiment - Operational - Kill switch - Permission minLength: 1 example: Release description: description: A description of what this Feature Toggle type could be used for type: string enum: - Enables trunk-based development for teams practicing continuous delivery - Performs multivariate or A/B testing - Controls operational aspects of the system behaviour # US English? - Gracefully degrades system functionality - Changez the features or product experiences that certain users receive minLength: 1 lifetimeDays: description: What's this? type: number example: 40 required: - version - types