Add user discoverable application API documentation

en/asgardeo/docs/apis/restapis/discoverable-application.yaml

@@ -0,0 +1,302 @@
+openapi: 3.0.0
+info:
+  description: >-
+    This document specifies the **User-visible application management RESTful API** for **WSO2 Identity Platform**.
+  version: "v1"
+  title: User Application Management API
+servers:
+  - url: 'https://api.asgardeo.io/t/{organization-name}/api/users/v1'
+security:
+  - OAuth2: []
+paths:
+  /me/applications:
+    get:
+      tags:
+        - Application Listing
+      summary: List applications
+      description: |
+        This API provides the capability to retrieve
+        the list of applications to an authorized user.
+
+        - <b>Scope(Permission) required:</b> `internal_login`
+
+        - <b>Flow type:</b> Authorization Code OAuth Flow
+      operationId: getApplications
+      parameters:
+        - $ref: '#/components/parameters/attributesQueryParam'
+        - $ref: '#/components/parameters/limitQueryParam'
+        - $ref: '#/components/parameters/offsetQueryParam'
+        - $ref: '#/components/parameters/filterQueryParam'
+        - $ref: '#/components/parameters/sortOrderQueryParam'
+        - $ref: '#/components/parameters/sortByQueryParam'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApplicationListResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/ServerError'
+        '501':
+          $ref: '#/components/responses/NotImplemented'
+      x-codeSamples:
+        - lang: Curl
+          source: |
+            curl -X 'GET' \
+            'https://api.asgardeo.io/t/{organization-name}/api/users/v1/me/applications?attributes=name%2C%20description%2C%20logo&limit=10&offset=5&filter=name%20sw%20sales&sortOrder=asc&sortBy=name' \
+            -H 'accept: application/json' \
+            -H 'Authorization: Bearer {bearer_token}'
+  '/me/applications/{applicationId}':
+    get:
+      tags:
+        - Application Listing
+      summary: Get application by ID
+      description: |
+        This API provides the capability to retrieve an application to an authorized user.
+
+        - <b>Scope(Permission) required:</b> `internal_login`
+
+        - <b>Flow type:</b> Authorization Code OAuth Flow
+      operationId: getApplication
+      parameters:
+        - name: applicationId
+          in: path
+          description: ID of the application.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApplicationResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/ServerError'
+      x-codeSamples:
+        - lang: Curl
+          source: |
+            curl -X 'GET' \
+            'https://api.asgardeo.io/t/{organization-name}/api/users/v1/me/applications/{application-id}' \
+            -H 'accept: application/json' \
+            -H 'Authorization: Bearer {bearer_token}'
+components:
+  parameters:
+    limitQueryParam:
+      in: query
+      name: limit
+      required: false
+      description: Maximum number of records to return.
+      schema:
+        type: integer
+        format: int32
+        minimum: 0
+        default: 30
+        example: 10
+    offsetQueryParam:
+      in: query
+      name: offset
+      required: false
+      description: Number of records to skip for pagination.
+      schema:
+        type: integer
+        format: int32
+        minimum: 0
+        default: 0
+        example: 5
+    filterQueryParam:
+      in: query
+      name: filter
+      required: false
+      description: Condition to filter the retrieval of records.
+      schema:
+        type: string
+      examples:
+        sw:
+          value: name sw sales
+          summary: Filter by `sw` operator
+        ew:
+          value: name ew force
+          summary: Filter by `ew` operator
+        co:
+          value: name co sales
+          summary: Filter by `co` operator
+        eq:
+          value: name eq salesforce
+          summary: Filter by `eq` operator
+    sortOrderQueryParam:
+      in: query
+      name: sortOrder
+      required: false
+      description: |
+        Define the order by which the retrieved records should be sorted.
+        _This parameter is not supported yet._
+      schema:
+        type: string
+        enum:
+          - asc
+          - desc
+        example: asc
+    sortByQueryParam:
+      in: query
+      name: sortBy
+      required: false
+      description: |
+        Attribute by which the retrieved records should be sorted.
+        _This parameter is not supported yet._
+      schema:
+        type: string
+      example: name
+    attributesQueryParam:
+      in: query
+      name: attributes
+      required: false
+      description: >-
+        Define only the required attributes to be sent in the response object as a comma-separated string.
+      schema:
+        type: string
+      example: name, description, logo
+  responses:
+    NotFound:
+      description: The specified resource is not found.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Unauthorized:
+      description: Unauthorized.
+    ServerError:
+      description: Internal Server Error.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    NotImplemented:
+      description: Not Implemented.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    BadRequest:
+      description: Bad Request.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Forbidden:
+      description: Resource Forbidden.
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      description: "You can use the following OAuth grant type to securely access the respective API endpoints.
+      \n\n **Authorization Code OAuth Flow**
+      \n\n Authorization URL: 'https://api.asgardeo.io/t/{org-name}/oauth2/authorize'
+      \n\n Token URL: 'https://api.asgardeo.io/t/{org-name}/oauth2/token'
+      \n\n This flow type is used for the `me/applications` endpoints. You can use the following scope for these endpoints.
+        \n\n - ```internal_login```: Grant permission for an authenticated user for self management."
+      flows:
+        authorizationCode:
+          authorizationUrl: 'https://api.asgardeo.io/t/{organization-name}/oauth2/authorize'
+          tokenUrl: 'https://api.asgardeo.io/t/{organization-name}/oauth2/token'
+          scopes:
+            internal_login: Grant permission for an authenticated user for self management.
+  schemas:
+    ApplicationListResponse:
+      type: object
+      properties:
+        totalResults:
+          type: integer
+          description: The total number of results matching the query.
+          example: 30
+        startIndex:
+          type: integer
+          description: The 1-based index of the first result in the current set of results.
+          example: 5
+        count:
+          type: integer
+          description: Number of results returned in response.
+          example: 1
+        applications:
+          type: array
+          description: Applications matching the query.
+          items:
+            $ref: '#/components/schemas/ApplicationResponse'
+        links:
+          type: array
+          description: Navigation links.
+          items:
+            $ref: '#/components/schemas/Link'
+          example:
+            - href: '/api/users/v1/me/applications?offset=10&limit=10'
+              rel: 'next'
+            - href: '/api/users/v1/me/applications?offset=0&limit=5'
+              rel: 'previous'
+            - href: '/api/users/v1/me/applications?offset=0&limit=10'
+              rel: 'first'
+            - href: '/api/users/v1/me/applications?offset=20&limit=10'
+              rel: 'last'
+
+    ApplicationResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          example: 85e3f4b8-0d22-4181-b1e3-1651f71b88bd
+        name:
+          type: string
+          example: Salesforce
+        description:
+          type: string
+          example: Customer relationship management application
+        image:
+          type: string
+          format: uri
+          example: 'https://example.com/logo/mysalesforce-logo.png'
+        accessUrl:
+          type: string
+          format: uri
+          example: 'https://example.my.salesforce.com/'
+    Link:
+      type: object
+      properties:
+        href:
+          type: string
+          format: uri
+          description: Path to the target resource.
+        rel:
+          type: string
+          description: Describes how the current context is related to the target resource.
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          example: UAM-10000
+        message:
+          type: string
+          example: Some Error Message
+        description:
+          type: string
+          example: Some Error Description
+        traceId:
+          type: string
+          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047

en/asgardeo/docs/apis/user-discoverable-applications.md

@@ -0,0 +1,5 @@
+---
+template: templates/redoc.html
+---
+
+<redoc spec-url="{{base_path}}/apis/restapis/discoverable-application.yaml" theme='{{redoc_theme}}'></redoc>

en/asgardeo/mkdocs.yml

@@ -959,6 +959,7 @@ nav:
       - Push Notification Device API: apis/push-notification-device-rest-api.md
       - User account associations API: apis/association-management-by-user.md
       - User credential management API: apis/end-user-credential-management-v2-rest-api.md
+      - User discoverable application API: apis/user-discoverable-applications.md
       - Export user information API: apis/export-user-info.md
       - Identity Verification: apis/user-identity-verification.md
       - Organization Me API: apis/user-organization-api.md