#   Copyright (c) 2020, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
#---------------------------------------------------------------------------

openapi: "3.0.0"
info:
  title: Service Catalog APIs
  description: |
    This specifies a **RESTful API** for Service Catalog.

    # Authentication
    Our REST APIs are protected using OAuth2 and access control is achieved through scopes. Before you start invoking
    the the API you need to obtain an access token with the required scopes. This guide will walk you through the steps
    that you will need to follow to obtain an access token.
    First you need to obtain the consumer key/secret key pair by calling the dynamic client registration (DCR) endpoint. You can add your preferred grant types
    in the payload. A Sample payload is shown below.
    ```
      {
      "callbackUrl":"www.google.lk",
      "clientName":"rest_api_service_catalog",
      "owner":"admin",
      "grantType":"client_credentials password refresh_token",
      "saasApp":true
      }
    ```
    Create a file (payload.json) with the above sample payload, and use the cURL shown bellow to invoke the DCR endpoint. Authorization header of this should contain the
    base64 encoded admin username and password.
    **Format of the request**
    ```
      curl -X POST -H "Authorization: Basic Base64(admin_username:admin_password)" -H "Content-Type: application/json"
      \ -d @payload.json https://<host>:<servlet_port>/client-registration/v0.17/register
    ```
    **Sample request**
    ```
      curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json"
      \ -d @payload.json https://localhost:9443/client-registration/v0.17/register
    ```
    Following is a sample response after invoking the above curl.
    ```
    {
    "clientId": "fOCi4vNJ59PpHucC2CAYfYuADdMa",
    "clientName": "rest_api_service_catalog",
    "callBackURL": "www.google.lk",
    "clientSecret": "a4FwHlq0iCIKVs2MPIIDnepZnYMa",
    "isSaasApplication": true,
    "appOwner": "admin",
    "jsonString": "{\"grant_types\":\"client_credentials password refresh_token\",\"redirect_uris\":\"www.google.lk\",\"client_name\":\"rest_api123\"}",
    "jsonAppAttribute": "{}",
    "tokenType": null
    }
    ```
    Next you must use the above client id and secret to obtain the access token.
    We will be using the password grant type for this, you can use any grant type you desire.
    You also need to add the proper **scope** when getting the access token. All possible scopes for Service Catalog REST API can be viewed in **OAuth2 Security** section
    of this document and scope for each resource is given in **authorization** section of resource documentation.
    Following is the format of the request if you are using the password grant type.
    ```
    curl -k -d "grant_type=password&username=<admin_username>&password=<admin_passowrd>&scope=<scopes seperated by space>"
    \ -H "Authorization: Basic base64(cliet_id:client_secret)"
    \ https://<host>:<servlet_port>/oauth2/token
    ```
    **Sample request**
    ```
    curl https://localhost:9443/oauth2/token -k \
    -H "Authorization: Basic Zk9DaTR2Tko1OVBwSHVjQzJDQVlmWXVBRGRNYTphNEZ3SGxxMGlDSUtWczJNUElJRG5lcFpuWU1h" \
    -d "grant_type=password&username=admin&password=admin&scope=service_catalog:service_view service_catalog:service_write"
    ```
    Shown below is a sample response to the above request.
    ```
    {
    "access_token": "e79bda48-3406-3178-acce-f6e4dbdcbb12",
    "refresh_token": "a757795d-e69f-38b8-bd85-9aded677a97c",
    "scope": "service_catalog:service_view service_catalog:service_write",
    "token_type": "Bearer",
    "expires_in": 3600
    }
    ```
    Now you have a valid access token, which you can use to invoke an API.
    Navigate through the API descriptions to find the required API, obtain an access token as described above and invoke the API with the authentication header.
    If you use a different authentication mechanism, this process may change.

  version: '1.2'
servers:
  - url: 'https://apis.wso2.com/api/service-catalog/v1'
  - url: 'http://apis.wso2.com/api/service-catalog/v1'

paths:
  ######################################################
  # The Service Catalog API operations
  ######################################################
  /services:
  
    #-----------------------------------------------------
    # Retrieve/search services in the service catalog
    #-----------------------------------------------------
    get:
      summary: Retrieve/search services
      description: |
        Retrieve or search services in the service catalog of the user's organization or tenant. Search is supported
        using the name, version, definitionType and key of the service.
        Search based on the definition type and key of the service will always be an exact search. If you want to
        execute an exact search for either name or version the parameter should be given inside double quotation.
      operationId: searchServices
      security:
        - OAuth2Security:
            - service_catalog:service_view
            - apim:api_view
      tags:
        - Services
      parameters:
        - name: name
          in: query
          description: |
            Filter services by the name of the service
          schema:
            type: string
        - name: version
          in: query
          description: |
            Filter services by version of the service
          schema:
            type: string
        - name: definitionType
          in: query
          description: |
            Filter services by definitionType
          schema:
            type: string
            enum:
              - OAS
              - WSDL1
              - WSDL2
              - GRAPHQL_SDL
              - ASYNC_API
        - name: key
          in: query
          description: |
            Comma seperated keys of the services to check
          schema:
            type: string
        - name: shrink
          in: query
          description: |
            If this set to true, a minimal set of fields will be provided for each service including the md5
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/sortBy'
        - $ref: '#/components/parameters/sortOrder'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        200:
          description: |
            Paginated matched list of services returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceList'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          label: Exact search by name
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                    "https://127.0.0.1:9443/api/am/service-catalog/v1/services?name=%22Pet%20Service%22"'
        - lang: Curl
          label: Matching search by name
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                    "https://127.0.0.1:9443/api/am/service-catalog/v1/services?name=Pet%20Service"'
        - lang: Curl
          label: Exact search by version
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                    "https://127.0.0.1:9443/api/am/service-catalog/v1/services?version=%221.0.0%22"'
        - lang: Curl
          label: Matching search by version
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                    "https://127.0.0.1:9443/api/am/service-catalog/v1/services?version=1.0.0"'
        - lang: Curl
          label: Get all versions of a service
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                    "https://127.0.0.1:9443/api/am/service-catalog/v1/services?name=%22Pet%20Service%22"'

    #-----------------------------------------------------
    # Adds new service to the service catalog
    #-----------------------------------------------------
    post:
      summary: Add a new service to Service Catalog
      description: |
        Add a new service to the service catalog of the user's organization (or tenant)
        by specifying the details of the service along with its definition. 
      security:
        - OAuth2Security:
            - service_catalog:service_write
      tags:
        - Services
      operationId: addService
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ServiceSchema'
      responses:
        201:
          description: |
            Created.
            Successful response with the newly created service as the response payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
          -F "definitionFile=@definition.yaml" -F "serviceMetadata=@metadata.json;type=application/json" "https://127.0.0.1:9443/api/am/service-catalog/v1/services"'

  /services/{serviceId}:
    #-----------------------------------------------------
    # Retrieve a specific service in the service catalog
    #-----------------------------------------------------
    get:
      summary: Get details of a service
      description: |
        Get details of a service using the id of the service.
      security:
        - OAuth2Security:
            - service_catalog:service_view
            - apim:api_view
      operationId: getServiceById
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        200:
          description: |
            Requested service in the service catalog is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                "https://127.0.0.1:9443/api/am/service-catalog/v1/services"'

    #-----------------------------------------------------
    # Update a service in the service catalog
    #-----------------------------------------------------
    put:
      summary: Update a service
      description: |
        Update a service's details and definition
      security:
        - OAuth2Security:
            - service_catalog:service_write
      operationId: updateService
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/serviceId'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ServiceSchema'
      responses:
        200:
          description: |
            Updated.
            Successful response with the newly updated service as entity in the body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -X PUT -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
          -F "definitionFile=@definition.yaml" -F "serviceMetadata=@metadata.json;type=application/json"
           "https://127.0.0.1:9443/api/am/service-catalog/v1/services/7b3d976a-620a-4435-9649-e806f30dc7cf"'

    #-----------------------------------------------------
    # Delete a service in the service catalog
    #-----------------------------------------------------
    delete:
      summary: Delete a service
      description: |
        Delete a service by providing the service id
      security:
        - OAuth2Security:
            - service_catalog:service_write
      operationId: deleteService
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        204:
          description: |
            Successfully deleted the catalog entry.
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -X DELETE -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                "https://127.0.0.1:9443/api/am/service-catalog/v1/services/32b4541f-ce7e-47a6-9c0c-c3db18128c50"'

  #-----------------------------------------------------
  # Retrieve definition of a service in the service catalog
  #-----------------------------------------------------
  /services/{serviceId}/definition:
    get:
      summary: Retrieve a service definition
      description: |
        Retrieve the definition of a service identified by the service id.
      security:
        - OAuth2Security:
            - service_catalog:service_view
            - apim:api_view
      operationId: getServiceDefinition
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        200:
          description: |
            Successful response with the definition file as entity in the body.
          content:
            application/json:
              schema:
                type: string
            application/yaml:
              schema:
                type: string
                format: binary
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
            "https://127.0.0.1:9443/api/am/service-catalog/v1/services/3784c2da-2f2a-4af9-8a43-ef207fb4d739/definition"'

  #-------------------------------------------------------------------
  # Retrieve the information of APIs that use a given service
  #-------------------------------------------------------------------
  /services/{serviceId}/usage:
    get:
      summary: Retrieve the API Info that use the given service
      description: |
        Retrieve the id, name, context and version of the APIs that used by the service
      security:
        - OAuth2Security:
            - service_catalog:service_view
            - apim:api_view
      operationId: getServiceUsage
      tags:
        - Services
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        200:
          description: |
            List of APIs that uses the service in the service catalog is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIList'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                "https://127.0.0.1:9443/api/am/service-catalog/v1/services/3784c2da-2f2a-4af9-8a43-ef207fb4d739/usage"'

  #-------------------------------------------------------------------
  # Import a service into the service catalog from a zipped archive
  #-------------------------------------------------------------------
  /services/import:
    post:
      summary: Import a service
      description: |
        Import  a service by providing an archived service
      security:
        - OAuth2Security:
            - service_catalog:service_write
      operationId: importService
      tags:
        - Services
      parameters:
        - name: overwrite
          in: query
          description: |
            Whether to overwrite if there is any existing service with the same name and version.
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        required: false
        content:
          multipart/form-data:
            schema:
              required:
                - file
              properties:
                file:
                  type: string
                  description: |
                    Zip archive consisting of exported Application Configuration.
                  format: binary
                verifier:
                  type: string
      responses:
        200:
          description: |
            Successful response with the imported service metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInfoList'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
              -F "file=@services.zip" "https://127.0.0.1:9443/api/am/service-catalog/v1/services/import?overwrite=true"'
                
  #----------------------------------------------------------
  # Exporting a service as a zipped archive
  #----------------------------------------------------------
  /services/export:

    #-----------------------------------------
    # Retrieve a service as a zipped archive
    #-----------------------------------------
    get:
      summary: Export a service
      description: |
        Export a service as an archived zip file.
      security:
        - OAuth2Security:
            - service_catalog:service_view
      operationId: exportService
      tags:
        - Services
      parameters:
        - name: name
          in: query
          description: |
            Name of the service to export
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: |
            Version of the service to export
          required: true
          schema:
            type: string
      responses:
        200:
          description: |
            Successful response as the exported service as a zipped archive.
          content:
            application/zip:
              schema:
                type: string
                format: binary
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
          "https://127.0.0.1:9443/api/am/service-catalog/v1/services/export?name=Single1Curl&version=1.0.0" > services.zip'

  ######################################################
  # The Service Catalog API settings
  ######################################################
  /settings:
    #-----------------------------------------------------
    # Retrieve Service Catalog settings
    #-----------------------------------------------------
    get:
      summary: Retrieve service catalog API settings
      description: |
        Retrieve Service Catalog API settings
      operationId: getSettings
      tags:
        - Settings
      responses:
        200:
          description: |
            OK.
            Settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settings'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'
      x-code-samples:
        - lang: Curl
          source: 'curl -k -H "Authorization: Bearer ae4eae22-3f65-387b-a171-d37eaa366fa8"
                  "https://127.0.0.1:9443/api/am/service-catalog/v1/settings"'

components:
  #-------------------------------------------------------
  # The security schemes of resources used by some of the APIs
  #-------------------------------------------------------
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        password:
          tokenUrl: https://localhost:9443/oauth2/token
          scopes:
            service_catalog:service_view: view access to services in service catalog
            service_catalog:service_write: write access to services in service catalog
            apim:api_view: view access to services for read only users

  #-------------------------------------------------------
  # The definitions of resources used by some of the APIs
  #-------------------------------------------------------
  schemas:
    ServiceInfoList:
      title: Services List
      type: object
      properties:
        count:
          type: integer
          description: |
            MD5 hashes of services returned.
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/ServiceInfo'
          
    ServiceListExpanded:
      title: Services List
      type: object
      properties:
        count:
          type: integer
          description: |
            MD5 hashes of services returned.
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/Service'
        pagination:
          $ref: '#/components/schemas/Pagination'

    APIList:
      title: API List
      type: object
      properties:
        count:
          type: integer
          description: |
            Number of APIs returned.
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/APIInfo'

    APIInfo:
      title: API Info object with basic API details.
      type: object
      properties:
        id:
          type: string
          example: 01234567-0123-0123-0123-012345678901
        name:
          type: string
          example: CalculatorAPI
        displayName:
          type: string
          example: Calculator API
          description: |
            Display name of the API.
            This is the name that will be displayed in the Publisher and DevPortal.
            If not provided, the name will be used as the display name.
        context:
          type: string
          example: CalculatorAPI
        version:
          type: string
          example: 1.0.0
        provider:
          type: string
          example: admin
          
    #-----------------------------------------------------
    # The Service Catalog Entry resource
    #-----------------------------------------------------
    Verifier:
      type: object
      title: Json array of md5 hash values of Service Catalog Entry objects
      required:
        - key
        - md5
      properties:
        key:
          type: string
          pattern: '^[^\*]+$'
          example: petStore-1.0.0
        md5:
          type: string
          example: e27ef979af14c72783b8112dc41c3434c09763ddb230e1a829d5f9134d1abd07

    #-----------------------------------------------------
    # The Paginated Service Entry Array resource
    #-----------------------------------------------------
    ServiceList:
      type: object
      title: Paginated List of Services in Service Catalog
      properties:
        list:
          type: array
          title: List of Services in Service Catalog
          items:
            $ref: '#/components/schemas/Service'
        pagination:
          $ref: '#/components/schemas/Pagination'

    #-----------------------------------------------------
    # The Service resource model
    #-----------------------------------------------------
    Service:
      type: object
      title: The Service Object
      required:
        - name
        - version
        - definitionType
        - serviceUrl
      properties:
        id:
          type: string
          example: 01234567-0123-0123-0123-012345678901
          readOnly: true
        name:
          type: string
          pattern: '^[^\*]+$'
          example: Pizzashack-Endpoint
          maxLength: 255
          minLength: 1
        description:
          type: string
          example: A Catalog Entry that exposes a REST endpoint
          maxLength: 1024
        version:
          type: string
          example: v1
          maxLength: 30
          minLength: 1
        serviceKey:
          type: string
          example: Pizzashack-Endpoint-1.0.0
          maxLength: 512
        serviceUrl:
          type: string
          example: http://localhost/pizzashack
        definitionType:
          type: string
          description: The type of the provided API definition
          example: OAS3
          enum:
            - OAS2
            - OAS3
            - WSDL1
            - WSDL2
            - GRAPHQL_SDL
            - ASYNC_API
        securityType:
          type: string
          description: The security type of the endpoint
          example: BASIC
          enum:
            - BASIC
            - DIGEST
            - OAUTH2
            - X509
            - API_KEY
            - NONE
          default: NONE
        mutualSSLEnabled:
          type: boolean
          description: Whether Mutual SSL is enabled for the endpoint
          default: false
          example: false
        usage:
          type: integer
          description: Number of usages of the service in APIs
          readOnly: true
          example: 1
        createdTime:
          type: string
          readOnly: true
          example: '2020-02-20T13:57:16.229'
        lastUpdatedTime:
          type: string
          readOnly: true
          example: '2020-02-20T13:57:16.229'
        md5:
          type: string
          example: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
        definitionUrl:
          type: string
          example: https://petstore.swagger.io/v2/swagger.json
    
    ServiceInfo:
      type: object
      title: The Service Info object
      properties:
        id:
          type: string
          example: 01234567-0123-0123-0123-012345678901
          readOnly: true
        name:
          type: string
          pattern: '^[^\*]+$'
          example: PizzashackEndpoint
        key:
          type: string
          example: PizzashackEndpoint-1.0.0
        version:
          type: string
          example: v1
        md5:
          type: string
          example: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
          
    #-----------------------------------------------------
    # The Service Schema resource
    #-----------------------------------------------------
    ServiceSchema:
      type: object
      title: The Service Schema object
      required:
        - serviceMetadata
      properties:
        serviceMetadata:
          $ref: '#/components/schemas/Service'
        definitionFile:
          type: string
          format: binary
        inlineContent:
          type: string
          description: Inline content of the document

    #-----------------------------------------------------
    # The settings resource
    #-----------------------------------------------------
    Settings:
      title: SettingsDTO
      properties:
        scopes:
          type: array
          items:
            type: string
            example: service_catalog:service_view

    #-----------------------------------------------------
    # The Error resource
    #-----------------------------------------------------
    Error:
      type: object
      title: Error object returned with 4XX HTTP Status
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int64
        message:
          type: string
          description: Error message.
        description:
          type: string
          description: |
            A detail description about the error message.
        moreInfo:
          type: string
          description: |
            Preferably an url with more details about the error.
        error:
          type: array
          description: |
            If there are more than one error list them out.
            For example, list out validation errors by each field.
          items:
            $ref: '#/components/schemas/ErrorListItem'

    #-----------------------------------------------------
    # The Error List Item resource
    #-----------------------------------------------------
    ErrorListItem:
      type: object
      title: Description of individual errors that may have occurred during a request.
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
          description: |
            Description about individual errors occurred
        description:
          type: string
          description: |
            A detail description about the error message.

    #-----------------------------------------------------
    # The pagination resource
    #-----------------------------------------------------
    Pagination:
      title: Pagination
      properties:
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 1
        total:
          type: integer
          example: 10
        next:
          type: string
          description: |
            Link to the next subset of resources qualified.
            Empty if no more resources are to be returned.
        previous:
          type: string
          description: |
            Link to the previous subset of resources qualified.
            Empty if current subset is the first subset returned.

  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
            moreInfo: ""
            error: []

    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: []

    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: []

    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: []

    UnsupportedMediaType:
      description: Unsupported Media Type. The entity of the request was not in a
        supported format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 415
            message: Unsupported media type
            description: The entity of the request was not in a supported format
            moreInfo: ""
            error: []

  ######################################################
  # Parameters - required by some of the APIs above
  ######################################################
  parameters:

    #-------------------------------------------------------
    # serviceId - An id which represents a service in the service catalog
    #-------------------------------------------------------
    serviceId:
      name: serviceId
      in: path
      description: uuid of the service
      required: true
      schema:
        type: string
        
    #-------------------------------------------------------
    # serviceKey - A key which represents a service in the service catalog
    #-------------------------------------------------------
    serviceKey:
      name: serviceKey
      in: path
      description: service key of the service
      required: true
      schema:
        type: string

    #-------------------------------------------------------
    # ifMatch - If-Match header value to be used for concurrency control
    #-------------------------------------------------------
    ifMatch:
      name: If-Match
      in: header
      description: ETag of the service resource to update
      required: false
      schema:
        type: string

    #-----------------------------------------------------
    # limit - The maximum number of resources to be returned by a GET
    #-----------------------------------------------------
    limit:
      name: limit
      in: query
      description: |
        Maximum limit of items to return.
      schema:
        type: integer
        default: 25

    #-------------------------------------------------------------------------------
    # offset - The order number of an instance in a qualified set of
    # resources at which to start to return the next batch of qualified resources
    #-------------------------------------------------------------------------------
    offset:
      name: offset
      in: query
      description: |
        Starting point within the complete list of items qualified.
      schema:
        type: integer
        default: 0

    #-------------------------------------------------------------------------------
    # sortBy - sort the returned services list by given field
    #-------------------------------------------------------------------------------
    sortBy:
      name: sortBy
      in: query
      schema:
        type: string
        enum:
          - name
          - definitionType
    
    #-------------------------------------------------------------------------------
    # sortOrder - sort ordering: ascending (asc) or descending (desc)
    #-------------------------------------------------------------------------------
    sortOrder:
      name: sortOrder
      in: query
      schema:
        type: string
        enum:
          - asc
          - desc

  headers:
    #-------------------------------------------------------
    # ETag header representing the current state of the resource
    #-------------------------------------------------------
    ETag:
      schema:
        type: string
      description: A hash-like string value which represents the current state of a resource