openapi: 3.0.0
info:
  description: >
    This document specifies an **API Resource Management RESTful API** for **WSO2
    Identity Server**.
  version: "v1"
  title: WSO2 Identity Server - API Resource Management Rest API
  termsOfService: 'http://swagger.io/terms/'
  contact:
    name: WSO2
    url: 'http://wso2.com/products/identity-server/'
    email: architecture@wso2.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

security:
  - OAuth2: []
  - BasicAuth: []

servers:
  - url: 'https://{server-url}/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        default: "carbon.super"
      server-url:
        default: "localhost:9443"

paths:
  /api-resources:
    post:
      tags:
        - API Resources
      operationId: addAPIResource
      summary: Add a new API resource
      description: > 
        Add a new API resource
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/create <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_create
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResourceResponse'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIResourceCreationModel'
        description: This represents the API resource to be created.
        required: true
    get:
      tags:
        - API Resources
      summary: List all API resources in the server
      description: > 
        List all API resources in the server
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/view <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_view
      operationId: getAPIResources
      parameters:
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/attributes'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResourceListResponse'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api-resources/{apiResourceId}:
    get:
      tags:
        - API Resources
      summary: Get API resource specified by the id
      description: > 
        Get API resource specified by the id
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/view <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_view
      parameters:
        - $ref: '#/components/parameters/apiResourceId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResourceResponse'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    patch:
      tags:
        - API Resources
      summary: Patch API resource specified by the id
      description: > 
        Patch API resource specified by the id. Patch operation only supports "name", "description" updating and "addedScopes" fields at the moment.
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/update <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_update
      parameters:
        - $ref: '#/components/parameters/apiResourceId'
      responses:
        204:
          description: Not Content
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        501:
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIResourcePatchModel'
        description: This represents the API resource to be patched.
        required: true
    delete:
      tags:
        - API Resources
      summary: Delete API resource specified by the id
      description: > 
        Delete API resource specified by the id
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/delete <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_delete
      parameters:
        - $ref: '#/components/parameters/apiResourceId'
      responses:
        204:
          description: No Content
        401:
          description: Unauthorized
        403:
          description: Forbidden
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api-resources/{apiResourceId}/scopes:
    get:
      tags:
        - API Resource Scopes
      summary: Get API resource scopes
      description: > 
        Get API resource scopes specified by the id
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/view <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_view
      parameters:
        - $ref: '#/components/parameters/apiResourceId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScopeGetModel'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - API Resource Scopes
      summary: Add scopes to API resource
      description: > 
        Put scopes API resource specified by the id
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/update <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_update
      parameters:
        - $ref: '#/components/parameters/apiResourceId'
      responses:
        204:
          description: No Content
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ScopeCreationModel'
        description: This represents the API resource to be patched.
        required: true

  /api-resources/{apiResourceId}/scopes/{scopeName}:
    delete:
      tags:
        - API Resource Scopes
      summary: Delete API scope specified by the name
      description: > 
        Delete API scope specified by the name
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/delete <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_delete
      parameters:
        - $ref: '#/components/parameters/apiResourceId'
        - $ref: '#/components/parameters/scopeName'
      responses:
        401:
          description: Unauthorized
        403:
          description: Forbidden
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /scopes:
    get:
      tags:
        - API Resource Scopes
      summary: Get all scopes in the tenant
      description: > 
        Get all scopes in the tenant
        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/apiresourcemgt/view <br>
        <b>Scope required:</b> <br>
          * internal_api_resource_view
      parameters:
        - $ref: '#/components/parameters/filter'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScopeGetModel'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  parameters:
    organizationId:
      in: path
      name: organizationId
      description: uuid of the org.
      required: true
      schema:
        type: string
        example: "1234-4567-4567"

    apiResourceId:
      name: apiResourceId
      in: path
      description: ID of the API Resource.
      required: true
      schema:
        type: string
        example: er34-gf23-bv54-vb90

    scopeName:
      name: scopeName
      in: path
      description: Name of the Scope.
      required: true
      schema:
        type: string

    applicationId:
      name: applicationId
      in: path
      description: ID of the Application.
      required: true
      schema:
        type: string

    authorizationId:
      name: authorizationId
      in: path
      description: ID of the authorization.
      required: true
      schema:
        type: string

    before:
      name: before
      in: query
      required: false
      description: |
        Base64 encoded cursor value for backward pagination.
      schema:
        type: string
      example: Ng==

    after:
      name: after
      in: query
      required: false
      description: |
        Base64 encoded cursor value for forward pagination.
      schema:
        type: string
      example: Ng==

    filter:
      name: filter
      in: query
      required: false
      description: |
        Condition to filter the retrieval of records. Supports 'sw', 'co', 'ew' and 'eq' operations.
      schema:
        type: string
      example: identifier+eq+greetings

    limit:
      name: limit
      in: query
      required: false
      description: |
        Maximum number of records to return.
      schema:
        type: integer
      example: 10

    attributes:
      name: attributes
      in: query
      required: false
      description: Specifies the required attributes in the response. Only 'properties' attribute is currently supported.
      schema:
        type: string

  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          example: AAA-00000
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047

    APIResourceListItem:
      type: object
      required:
        - id
        - name
        - identifier
        - self
      properties:
        id:
          type: string
          example: gh43-jk34-vb34-df67
        name:
          type: string
          example: Greetings API
        identifier:
          type: string
          example: greetings_api
        type:
          type: string
          example: SYSTEM
        requiresAuthorization:
          type: boolean
          example: true
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Property'
        self:
          type: string
          example: /t/carbon.super/api/server/v1/api-resources/eDUwOUNlcnRpZmljYXRlQXV0aGVudGljYXRvcg

    APIResourceResponse:
      type: object
      required:
        - id
        - name
        - identifier
        - self
      properties:
        id:
          type: string
          example: gh43-jk34-vb34-df67
        name:
          type: string
          example: Greetings API
        description:
          type: string
          example: Greeting API representation
        identifier:
          type: string
          example: greetings_api
        type:
          type: string
          example: SYSTEM
        requiresAuthorization:
          type: boolean
          example: true
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/ScopeGetModel'
        subscribedApplications:
          type: array
          items:
            $ref: '#/components/schemas/SubscribedApplicationGetModel'
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Property'
        self:
          type: string
          example: /t/carbon.super/api/server/v1/api-resources/eDUwOUNlcnRpZmljYXRlQXV0aGVudGljYXRvcg

    APIResourceCreationModel:
      type: object
      required:
        - identifier
        - name
      properties:
        name:
          type: string
          example: Greetings API
        identifier:
          type: string
          example: greetings_api
        description:
          type: string
          example: Greetings API representation
        requiresAuthorization:
          type: boolean
          example: true
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/ScopeCreationModel'

    APIResourcePatchModel:
      type: object
      properties:
        name:
          type: string
          example: Greetings API
        description:
          type: string
          example: Greetings API representation
        addedScopes:
          type: array
          items:
            $ref: '#/components/schemas/ScopeCreationModel'
        removedScopes:
          type: array
          items:
            type: string
          description: This field is not supported yet.

    PaginationLink:
      type: object
      properties:
        rel:
          type: string
          example: before
        href:
          type: string
          example: /o/orgName/api-resources?after=NDoy

    APIResourceListResponse:
      type: object
      required:
        - links
      properties:
        totalResults:
          type: integer
          example: 1
        links:
          type: array
          items:
            $ref: '#/components/schemas/PaginationLink'
        APIResources:
          type: array
          items:
            $ref: '#/components/schemas/APIResourceListItem'

    ScopeGetModel:
      type: object
      required:
        - id
        - displayName
        - name
      properties:
        id:
          type: string
          example: sf23-fg34-fy53-hj23
        displayName:
          type: string
          example: Write
        name:
          type: string
          example: greetings:write
        description:
          type: string
          example: Allow writing greetings

    ScopeCreationModel:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: 'greetings:write'
        displayName:
          type: string
          example: "Write Greetings"
        description:
          type: string
          example: "Allows writing greetings"

    SubscribedApplicationGetModel:
      type: object
      properties:
        name:
          type: string
          example: Application1
        id:
          type: string
          example: 23fd-23gd-54vv-sdhf

    Property:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          example: "label"
        value:
          type: string
          example: "Internal"

  responses:
    BadRequest:
      description: Bad Request. Invalid request or validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
            description: Invalid request or validation error

    Conflict:
      description: Conflict. Specified resource already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 409
            message: Conflict
            description: Specified resource already exists
            moreInfo: ''
            error: []
    Forbidden:
      description: >-
        Forbidden. The request must be conditional but no condition has been
        specified.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden
            description: >-
              The request must be conditional but no condition has been
              specified
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
            description: >-
              The server encountered an internal error. Please contact
              administrator.
            moreInfo: ''
            error: []
    NotFound:
      description: Not Found. The specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not Found
            description: The specified resource does not exist
            moreInfo: ''
            error: []

    Unauthorized:
      description: Unauthorized. The user is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized
            description: The user is not authorized
            moreInfo: ''
            error: []

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'http://localhost:9443/oauth2/token'
          scopes: {}
