-
Notifications
You must be signed in to change notification settings - Fork 317
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4905 from malithie/rules-metadata-api
Add API docs for Rule Metadata API
- Loading branch information
Showing
6 changed files
with
759 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,369 @@ | ||
| openapi: 3.0.1 | ||
| info: | ||
| title: Asgardeo Rule Metadata REST API | ||
| description: "The Rule Metadata API provides the essential metadata required to configure rules dynamically based on the flow context. \nThe metadata retrieved by this API is designed to support rule configuration in the user interface (UI) by delivering information about each configurable field, the set of applicable comparison operators (e.g., equals, contains) for each field, and lists of possible values or options for fields.\n" | ||
| contact: | ||
| name: WSO2 | ||
| url: https://wso2.com/identity-and-access-management/ | ||
| license: | ||
| name: Apache 2.0 | ||
| url: https://www.apache.org/licenses/LICENSE-2.0.html | ||
| version: v1 | ||
| servers: | ||
| - url: 'https://api.asgardeo.io/t/{organization-name}/api/server/v1' | ||
| security: | ||
| - OAuth2: [] | ||
| paths: | ||
| /rules/metadata: | ||
| get: | ||
| tags: | ||
| - Metadata | ||
| summary: Get metadata for rule configuration. | ||
| description: |+ | ||
| This API provides a list of fields, associated metadata, and applicable operators for each field based on the specified flow type. This information is used to populate the UI for rule configuration. | ||
| <b>Scope (Permission) required:</b> ``internal_rule_metadata_view`` | ||
| operationId: getExpressionMeta | ||
| parameters: | ||
| - name: flow | ||
| in: query | ||
| description: | | ||
| Specifies the flow to retrieve rule metadata. This ensures that the metadata returned is relevant to the given flow. | ||
| Note: At present, only the 'preIssueAccessToken' flow is supported. | ||
| required: true | ||
| style: form | ||
| explode: true | ||
| schema: | ||
| type: string | ||
| enum: | ||
| - preIssueAccessToken | ||
| - prePasswordUpdate | ||
| - preProfileUpdate | ||
| - preLogin | ||
| - postLogin | ||
| - inLogin | ||
| - preRegistration | ||
| - inRegistration | ||
| - inPasswordExpiry | ||
| responses: | ||
| "200": | ||
| description: Applicable fields and operators | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ExpressionMeta' | ||
| examples: | ||
| preIssueAccessToken: | ||
| summary: Sample response for pre-issue access token flow | ||
| value: | ||
| - field: | ||
| name: application | ||
| displayName: application | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| value: | ||
| inputType: options | ||
| valueType: reference | ||
| valueReferenceAttribute: id | ||
| valueDisplayAttribute: name | ||
| links: | ||
| - href: /applications?offset=0&limit=10 | ||
| method: GET | ||
| rel: values | ||
| - href: /applications?filter=name+eq+*&limit=10 | ||
| method: GET | ||
| rel: filter | ||
| - field: | ||
| name: grantType | ||
| displayName: grant type | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| value: | ||
| inputType: options | ||
| valueType: string | ||
| values: | ||
| - name: authorization_code | ||
| displayName: authorization code | ||
| - name: password | ||
| displayName: password | ||
| - name: refresh_token | ||
| displayName: refresh token | ||
| - name: client_credentials | ||
| displayName: client credentials | ||
| - name: urn:ietf:params:oauth:grant-type:token-exchange | ||
| displayName: token exchange | ||
| prePasswordUpdate: | ||
| summary: Sample response for pre-password update flow | ||
| value: | ||
| - field: | ||
| name: initiator | ||
| displayName: initiator | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| value: | ||
| inputType: options | ||
| valueType: string | ||
| values: | ||
| - name: user | ||
| displayName: user | ||
| - name: admin | ||
| displayName: admin | ||
| - name: application | ||
| displayName: application | ||
| - field: | ||
| name: flow | ||
| displayName: flow | ||
| dependentFileds: | ||
| - initiator | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| value: | ||
| inputType: options | ||
| valueType: string | ||
| values: | ||
| - name: reset | ||
| displayName: reset | ||
| - name: update | ||
| displayName: update | ||
| inLogin: | ||
| summary: Sample response for login flow | ||
| value: | ||
| - field: | ||
| name: role | ||
| displayName: user.role | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| value: | ||
| inputType: options | ||
| valueType: reference | ||
| valueReferenceAttribute: id | ||
| valueDisplayAttribute: name | ||
| links: | ||
| - href: /scim2/Roles?offset=0&limit=10 | ||
| method: GET | ||
| rel: values | ||
| - href: /scim2/Roles?filter=name+eq+*&limit=10 | ||
| method: GET | ||
| rel: filter | ||
| - field: | ||
| name: group | ||
| displayName: user.group | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| value: | ||
| inputType: options | ||
| valueType: reference | ||
| valueReferenceAttribute: id | ||
| valueDisplayAttribute: name | ||
| links: | ||
| - href: /scim2/Groups?offset=0&limit=10 | ||
| method: GET | ||
| rel: values | ||
| - href: /scim2/Groups?filter=name+eq+*&limit=10 | ||
| method: GET | ||
| rel: filter | ||
| - field: | ||
| name: email | ||
| displayName: user.email | ||
| operators: | ||
| - name: equals | ||
| displayName: equals | ||
| - name: notEquals | ||
| displayName: not equals | ||
| - name: startsWith | ||
| displayName: starts with | ||
| - name: endsWith | ||
| displayName: ends with | ||
| - name: contains | ||
| displayName: contains | ||
| value: | ||
| inputType: input | ||
| valueType: string | ||
| "400": | ||
| description: Bad Request | ||
| "401": | ||
| description: Unauthorized | ||
| "500": | ||
| description: Server Error | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/Error' | ||
| x-codeSamples: | ||
| - lang: Curl | ||
| source: | | ||
| curl --location 'https://api.asgardeo.io/t/{organization-name}/api/server/v1/rules/metadata?flow=preIssueAccessToken' \ | ||
| --header 'Authorization: Bearer {bearer_token}' | ||
| components: | ||
| schemas: | ||
| ExpressionMeta: | ||
| type: array | ||
| description: Represents the metadata for rule expressions. It includes field definitions and associated operators. | ||
| items: | ||
| $ref: '#/components/schemas/FieldDefinition' | ||
| FieldDefinition: | ||
| type: object | ||
| properties: | ||
| field: | ||
| $ref: '#/components/schemas/Field' | ||
| operators: | ||
| type: array | ||
| description: | | ||
| Specifies the list of valid operators that can be applied to this field in rule expressions. Each operator defines a comparison or matching condition (e.g., \"equals\", \"contains\", \"greaterThan\") that determines how the field's value will be evaluated within a rule. | ||
| items: | ||
| $ref: '#/components/schemas/Operator' | ||
| value: | ||
| $ref: '#/components/schemas/Value' | ||
| Field: | ||
| type: object | ||
| properties: | ||
| name: | ||
| type: string | ||
| description: Name of the field. This is an immutable attribute and uniquely identifies the field allowed in the rule. | ||
| example: role | ||
| displayName: | ||
| type: string | ||
| description: Display name of the field. Use as a user friendly label of the field to show in UI. | ||
| example: user.role | ||
| dependantFields: | ||
| type: array | ||
| description: Lists the names of fields on which this field depends for its display or selection in the next expression. | ||
| example: [] | ||
| items: | ||
| type: string | ||
| Value: | ||
| type: object | ||
| properties: | ||
| inputType: | ||
| type: string | ||
| description: | | ||
| Defines how the field should be presented and populated in the rule configuration UI. This property indicates whether the field allows direct user input or if the values are selected from predefined options. Possible types include: | ||
| - "input": Allows for direct user entry, such as text or numeric input. | ||
| - "options": Provides a list of selectable values, often fetched from an external data source, enabling users to pick from predefined choices. | ||
| enum: | ||
| - input | ||
| - options | ||
| valueType: | ||
| type: string | ||
| description: | | ||
| Specifies the expected data type for the field’s value within a rule expression. This property defines how the field's value should be interpreted when used in rule conditions. Possible types include: | ||
| - "string": Text value. | ||
| - "number": Numerical value. | ||
| - "boolean": True or false. | ||
| - "date": Date value. | ||
| - "reference": A reference to an external identifier, often used with options-type fields to indicate that the value is an ID or a unique attribute from related data." | ||
| enum: | ||
| - string | ||
| - number | ||
| - boolean | ||
| - date | ||
| - reference | ||
| valueReferenceAttribute: | ||
| type: string | ||
| description: "The key attribute in the options data (e.g., 'id') used to represent the option's selected value in rule expressions. Only available when 'valueType' is 'reference'." | ||
| example: id | ||
| valueDisplayAttribute: | ||
| type: string | ||
| description: "The attribute to show as the label for each option in the dropdown (e.g., 'name') when listing options. Only available when 'valueType' is 'reference'." | ||
| example: name | ||
| links: | ||
| type: array | ||
| description: Endpoints to retrieve or search for options dynamically. Included only when 'valueType' is 'reference'. | ||
| example: | ||
| - href: /scim2/roles?offset=0&limit=10 | ||
| method: GET | ||
| rel: values | ||
| - href: /scim2/roles/.search | ||
| method: GET | ||
| rel: filter | ||
| items: | ||
| $ref: '#/components/schemas/Link' | ||
| values: | ||
| type: array | ||
| description: "List of selectable values for options fields when 'valueType' is 'string', 'number', 'boolean', or 'date'." | ||
| items: | ||
| $ref: '#/components/schemas/ValueObject' | ||
| Operator: | ||
| type: object | ||
| properties: | ||
| name: | ||
| type: string | ||
| description: Name of the operator. The immutable identifier of the operator referenced within the rule expression. | ||
| displayName: | ||
| type: string | ||
| description: Display name of the operator. Use as a user friendly label of the operator to show in UI. | ||
| ValueObject: | ||
| type: object | ||
| properties: | ||
| name: | ||
| type: string | ||
| description: The name that uniquely identifies the option. | ||
| displayName: | ||
| type: string | ||
| description: The display name for the option. | ||
| Link: | ||
| type: object | ||
| properties: | ||
| href: | ||
| type: string | ||
| description: Url of the endpoint. | ||
| method: | ||
| type: string | ||
| description: Http method. | ||
| enum: | ||
| - GET | ||
| rel: | ||
| type: string | ||
| description: Indicates the endpoint’s relation to retrieving or filtering field values. | ||
| enum: | ||
| - values | ||
| - filter | ||
| Error: | ||
| type: object | ||
| properties: | ||
| code: | ||
| type: string | ||
| description: Error code | ||
| example: RMS-00000 | ||
| message: | ||
| type: string | ||
| description: Error message. | ||
| example: Some error message. | ||
| description: | ||
| type: string | ||
| description: Detailed error description. | ||
| example: Some error description. | ||
| traceId: | ||
| type: string | ||
| description: Trace identifier to refer at troubleshooting logs to troubleshoot the problem. | ||
| example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047 | ||
| securitySchemes: | ||
| OAuth2: | ||
| type: oauth2 | ||
| flows: | ||
| authorizationCode: | ||
| authorizationUrl: 'https://api.asgardeo.io/t/{org-name}/oauth2/authorize' | ||
| tokenUrl: 'https://api.asgardeo.io/t/{org-name}/oauth2/token' | ||
| scopes: | ||
| read: internal_rule_metadata_view |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| template: templates/redoc.html | ||
| --- | ||
|
|
||
| <redoc spec-url="{{base_path}}/apis/restapis/rule-metadata.yaml" theme='{{redoc_theme}}'></redoc> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.