openapi: 3.0.0
info:
  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.
  title: Service Catalog APIs
  version: "1.0"
servers:
- url: https://apis.wso2.com/api/service-catalog/v1
- url: http://apis.wso2.com/api/service-catalog/v1
paths:
  /services:
    get:
      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
      parameters:
      - description: |
          Filter services by the name of the service
        explode: true
        in: query
        name: name
        required: false
        schema:
          type: string
        style: form
      - description: |
          Filter services by version of the service
        explode: true
        in: query
        name: version
        required: false
        schema:
          type: string
        style: form
      - description: |
          Filter services by definitionType
        explode: true
        in: query
        name: definitionType
        required: false
        schema:
          enum:
          - OAS
          - WSDL1
          - WSDL2
          - GRAPHQL_SDL
          - ASYNC_API
          type: string
        style: form
      - description: |
          Comma seperated keys of the services to check
        explode: true
        in: query
        name: key
        required: false
        schema:
          type: string
        style: form
      - description: |
          If this set to true, a minimal set of fields will be provided for each service including the md5
        explode: true
        in: query
        name: shrink
        required: false
        schema:
          default: false
          type: boolean
        style: form
      - explode: true
        in: query
        name: sortBy
        required: false
        schema:
          enum:
          - name
          - definitionType
          type: string
        style: form
      - explode: true
        in: query
        name: sortOrder
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
        style: form
      - description: |
          Maximum limit of items to return.
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 25
          type: integer
        style: form
      - description: |
          Starting point within the complete list of items qualified.
        explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          type: integer
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceList'
          description: |
            Paginated matched list of services returned.
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_view
        - apim:api_view
      summary: Retrieve/search services
      tags:
      - Services
      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"'
      x-accepts: application/json
    post:
      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.
      operationId: addService
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ServiceSchema'
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
          description: |
            Created.
            Successful response with the newly created service as the response payload
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "415":
          content:
            application/json:
              example:
                code: 415
                message: Unsupported media type
                description: The entity of the request was not in a supported format
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsupported Media Type. The entity of the request was not in
            a supported format.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_write
      summary: Add a new service to Service Catalog
      tags:
      - Services
      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"'
      x-contentType: multipart/form-data
      x-accepts: application/json
  /services/{serviceId}:
    delete:
      description: |
        Delete a service by providing the service id
      operationId: deleteService
      parameters:
      - description: uuid of the service
        explode: false
        in: path
        name: serviceId
        required: true
        schema:
          type: string
        style: simple
      responses:
        "204":
          description: |
            Successfully deleted the catalog entry.
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "409":
          content:
            application/json:
              example:
                code: 409
                message: Conflict
                description: Specified resource already exists
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict. Specified resource already exists.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_write
      summary: Delete a service
      tags:
      - Services
      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"'
      x-accepts: application/json
    get:
      description: |
        Get details of a service using the id of the service.
      operationId: getServiceById
      parameters:
      - description: uuid of the service
        explode: false
        in: path
        name: serviceId
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
          description: |
            Requested service in the service catalog is returned.
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_view
        - apim:api_view
      summary: Get details of a service
      tags:
      - Services
      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"'
      x-accepts: application/json
    put:
      description: |
        Update a service's details and definition
      operationId: updateService
      parameters:
      - description: uuid of the service
        explode: false
        in: path
        name: serviceId
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ServiceSchema'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
          description: |
            Updated.
            Successful response with the newly updated service as entity in the body.
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_write
      summary: Update a service
      tags:
      - Services
      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"'
      x-contentType: multipart/form-data
      x-accepts: application/json
  /services/{serviceId}/definition:
    get:
      description: |
        Retrieve the definition of a service identified by the service id.
      operationId: getServiceDefinition
      parameters:
      - description: uuid of the service
        explode: false
        in: path
        name: serviceId
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
            application/yaml:
              schema:
                format: binary
                type: string
          description: |
            Successful response with the definition file as entity in the body.
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_view
        - apim:api_view
      summary: Retrieve a service definition
      tags:
      - Services
      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"'
      x-accepts: application/json
  /services/{serviceId}/usage:
    get:
      description: |
        Retrieve the id, name, context and version of the APIs that used by the service
      operationId: getServiceUsage
      parameters:
      - description: uuid of the service
        explode: false
        in: path
        name: serviceId
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIList'
          description: |
            List of APIs that uses the service in the service catalog is returned.
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_view
        - apim:api_view
      summary: Retrieve the API Info that use the given service
      tags:
      - Services
      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"'
      x-accepts: application/json
  /services/import:
    post:
      description: |
        Import  a service by providing an archived service
      operationId: importService
      parameters:
      - description: |
          Whether to overwrite if there is any existing service with the same name and version.
        explode: true
        in: query
        name: overwrite
        required: false
        schema:
          default: false
          type: boolean
        style: form
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  description: |
                    Zip archive consisting of exported Application Configuration.
                  format: binary
                  type: string
                verifier:
                  type: string
              required:
              - file
        required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceInfoList'
          description: |
            Successful response with the imported service metadata.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        "400":
          content:
            application/json:
              example:
                code: 400
                message: Bad Request
                description: Invalid request or validation error
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request. Invalid request or validation error.
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_write
      summary: Import a service
      tags:
      - Services
      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"'
      x-contentType: multipart/form-data
      x-accepts: application/json
  /services/export:
    get:
      description: |
        Export a service as an archived zip file.
      operationId: exportService
      parameters:
      - description: |
          Name of the service to export
        explode: true
        in: query
        name: name
        required: true
        schema:
          type: string
        style: form
      - description: |
          Version of the service to export
        explode: true
        in: query
        name: version
        required: true
        schema:
          type: string
        style: form
      responses:
        "200":
          content:
            application/zip:
              schema:
                format: binary
                type: string
          description: |
            Successful response as the exported service as a zipped archive.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      security:
      - OAuth2Security:
        - service_catalog:service_view
      summary: Export a service
      tags:
      - Services
      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'
      x-accepts: application/json
  /settings:
    get:
      description: |
        Retrieve Service Catalog API settings
      operationId: getSettings
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settings'
          description: |
            OK.
            Settings returned
        "401":
          content:
            application/json:
              example:
                code: 401
                message: Unauthorized
                description: The user is not authorized
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized. The user is not authorized.
        "404":
          content:
            application/json:
              example:
                code: 404
                message: Not Found
                description: The specified resource does not exist
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found. The specified resource does not exist.
        "500":
          content:
            application/json:
              example:
                code: 500
                message: Internal Server Error
                description: The server encountered an internal error. Please contact
                  administrator.
                moreInfo: ""
                error: []
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal Server Error.
      summary: Retrieve service catalog API settings
      tags:
      - Settings
      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"'
      x-accepts: application/json
components:
  headers:
    ETag:
      description: A hash-like string value which represents the current state of
        a resource
      explode: false
      schema:
        type: string
      style: simple
  parameters:
    serviceId:
      description: uuid of the service
      explode: false
      in: path
      name: serviceId
      required: true
      schema:
        type: string
      style: simple
    serviceKey:
      description: service key of the service
      explode: false
      in: path
      name: serviceKey
      required: true
      schema:
        type: string
      style: simple
    ifMatch:
      description: ETag of the service resource to update
      explode: false
      in: header
      name: If-Match
      required: false
      schema:
        type: string
      style: simple
    limit:
      description: |
        Maximum limit of items to return.
      explode: true
      in: query
      name: limit
      required: false
      schema:
        default: 25
        type: integer
      style: form
    offset:
      description: |
        Starting point within the complete list of items qualified.
      explode: true
      in: query
      name: offset
      required: false
      schema:
        default: 0
        type: integer
      style: form
    sortBy:
      explode: true
      in: query
      name: sortBy
      required: false
      schema:
        enum:
        - name
        - definitionType
        type: string
      style: form
    sortOrder:
      explode: true
      in: query
      name: sortOrder
      required: false
      schema:
        enum:
        - asc
        - desc
        type: string
      style: form
  responses:
    BadRequest:
      content:
        application/json:
          example:
            code: 400
            message: Bad Request
            description: Invalid request or validation error
            moreInfo: ""
            error: []
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad Request. Invalid request or validation error.
    InternalServerError:
      content:
        application/json:
          example:
            code: 500
            message: Internal Server Error
            description: The server encountered an internal error. Please contact
              administrator.
            moreInfo: ""
            error: []
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal Server Error.
    NotFound:
      content:
        application/json:
          example:
            code: 404
            message: Not Found
            description: The specified resource does not exist
            moreInfo: ""
            error: []
          schema:
            $ref: '#/components/schemas/Error'
      description: Not Found. The specified resource does not exist.
    Conflict:
      content:
        application/json:
          example:
            code: 409
            message: Conflict
            description: Specified resource already exists
            moreInfo: ""
            error: []
          schema:
            $ref: '#/components/schemas/Error'
      description: Conflict. Specified resource already exists.
    Unauthorized:
      content:
        application/json:
          example:
            code: 401
            message: Unauthorized
            description: The user is not authorized
            moreInfo: ""
            error: []
          schema:
            $ref: '#/components/schemas/Error'
      description: Unauthorized. The user is not authorized.
    UnsupportedMediaType:
      content:
        application/json:
          example:
            code: 415
            message: Unsupported media type
            description: The entity of the request was not in a supported format
            moreInfo: ""
            error: []
          schema:
            $ref: '#/components/schemas/Error'
      description: Unsupported Media Type. The entity of the request was not in a
        supported format.
  schemas:
    ServiceInfoList:
      example:
        count: 1
        list:
        - name: PizzashackEndpoint
          id: 01234567-0123-0123-0123-012345678901
          version: v1
          key: PizzashackEndpoint-1.0.0
          md5: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
        - name: PizzashackEndpoint
          id: 01234567-0123-0123-0123-012345678901
          version: v1
          key: PizzashackEndpoint-1.0.0
          md5: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
      properties:
        count:
          description: |
            MD5 hashes of services returned.
          example: 1
          type: integer
        list:
          items:
            $ref: '#/components/schemas/ServiceInfo'
          type: array
      title: Services List
      type: object
    ServiceListExpanded:
      properties:
        count:
          description: |
            MD5 hashes of services returned.
          example: 1
          type: integer
        list:
          items:
            $ref: '#/components/schemas/Service'
          type: array
        pagination:
          $ref: '#/components/schemas/Pagination'
      title: Services List
      type: object
    APIList:
      example:
        count: 1
        list:
        - provider: admin
          name: CalculatorAPI
          context: CalculatorAPI
          id: 01234567-0123-0123-0123-012345678901
          version: 1.0.0
        - provider: admin
          name: CalculatorAPI
          context: CalculatorAPI
          id: 01234567-0123-0123-0123-012345678901
          version: 1.0.0
      properties:
        count:
          description: |
            Number of APIs returned.
          example: 1
          type: integer
        list:
          items:
            $ref: '#/components/schemas/APIInfo'
          type: array
      title: API List
      type: object
    APIInfo:
      example:
        provider: admin
        name: CalculatorAPI
        context: CalculatorAPI
        id: 01234567-0123-0123-0123-012345678901
        version: 1.0.0
      properties:
        id:
          example: 01234567-0123-0123-0123-012345678901
          type: string
        name:
          example: CalculatorAPI
          type: string
        context:
          example: CalculatorAPI
          type: string
        version:
          example: 1.0.0
          type: string
        provider:
          example: admin
          type: string
      title: API Info object with basic API details.
      type: object
    Verifier:
      properties:
        key:
          example: petStore-1.0.0
          pattern: ^[^\*]+$
          type: string
        md5:
          example: e27ef979af14c72783b8112dc41c3434c09763ddb230e1a829d5f9134d1abd07
          type: string
      required:
      - key
      - md5
      title: Json array of md5 hash values of Service Catalog Entry objects
      type: object
    ServiceList:
      example:
        pagination:
          next: next
          total: 10
          offset: 0
          previous: previous
          limit: 1
        list:
        - usage: 1
          serviceUrl: http://localhost/pizzashack
          description: A Catalog Entry that exposes a REST endpoint
          definitionUrl: https://petstore.swagger.io/v2/swagger.json
          version: v1
          definitionType: OAS3
          securityType: BASIC
          name: Pizzashack-Endpoint
          mutualSSLEnabled: false
          createdTime: 2020-02-20T13:57:16.229
          lastUpdatedTime: 2020-02-20T13:57:16.229
          id: 01234567-0123-0123-0123-012345678901
          serviceKey: Pizzashack-Endpoint-1.0.0
          md5: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
        - usage: 1
          serviceUrl: http://localhost/pizzashack
          description: A Catalog Entry that exposes a REST endpoint
          definitionUrl: https://petstore.swagger.io/v2/swagger.json
          version: v1
          definitionType: OAS3
          securityType: BASIC
          name: Pizzashack-Endpoint
          mutualSSLEnabled: false
          createdTime: 2020-02-20T13:57:16.229
          lastUpdatedTime: 2020-02-20T13:57:16.229
          id: 01234567-0123-0123-0123-012345678901
          serviceKey: Pizzashack-Endpoint-1.0.0
          md5: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
      properties:
        list:
          items:
            $ref: '#/components/schemas/Service'
          title: List of Services in Service Catalog
          type: array
        pagination:
          $ref: '#/components/schemas/Pagination'
      title: Paginated List of Services in Service Catalog
      type: object
    Service:
      example:
        usage: 1
        serviceUrl: http://localhost/pizzashack
        description: A Catalog Entry that exposes a REST endpoint
        definitionUrl: https://petstore.swagger.io/v2/swagger.json
        version: v1
        definitionType: OAS3
        securityType: BASIC
        name: Pizzashack-Endpoint
        mutualSSLEnabled: false
        createdTime: 2020-02-20T13:57:16.229
        lastUpdatedTime: 2020-02-20T13:57:16.229
        id: 01234567-0123-0123-0123-012345678901
        serviceKey: Pizzashack-Endpoint-1.0.0
        md5: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
      properties:
        id:
          example: 01234567-0123-0123-0123-012345678901
          readOnly: true
          type: string
        name:
          example: Pizzashack-Endpoint
          maxLength: 255
          minLength: 1
          pattern: ^[^\*]+$
          type: string
        description:
          example: A Catalog Entry that exposes a REST endpoint
          maxLength: 1024
          type: string
        version:
          example: v1
          maxLength: 30
          minLength: 1
          type: string
        serviceKey:
          example: Pizzashack-Endpoint-1.0.0
          maxLength: 512
          type: string
        serviceUrl:
          example: http://localhost/pizzashack
          type: string
        definitionType:
          description: The type of the provided API definition
          enum:
          - OAS2
          - OAS3
          - WSDL1
          - WSDL2
          - GRAPHQL_SDL
          - ASYNC_API
          example: OAS3
          type: string
        securityType:
          default: NONE
          description: The security type of the endpoint
          enum:
          - BASIC
          - DIGEST
          - OAUTH2
          - X509
          - API_KEY
          - NONE
          example: BASIC
          type: string
        mutualSSLEnabled:
          default: false
          description: Whether Mutual SSL is enabled for the endpoint
          example: false
          type: boolean
        usage:
          description: Number of usages of the service in APIs
          example: 1
          readOnly: true
          type: integer
        createdTime:
          example: 2020-02-20T13:57:16.229
          readOnly: true
          type: string
        lastUpdatedTime:
          example: 2020-02-20T13:57:16.229
          readOnly: true
          type: string
        md5:
          example: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
          type: string
        definitionUrl:
          example: https://petstore.swagger.io/v2/swagger.json
          type: string
      required:
      - definitionType
      - name
      - serviceUrl
      - version
      title: The Service Object
      type: object
    ServiceInfo:
      example:
        name: PizzashackEndpoint
        id: 01234567-0123-0123-0123-012345678901
        version: v1
        key: PizzashackEndpoint-1.0.0
        md5: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
      properties:
        id:
          example: 01234567-0123-0123-0123-012345678901
          readOnly: true
          type: string
        name:
          example: PizzashackEndpoint
          pattern: ^[^\*]+$
          type: string
        key:
          example: PizzashackEndpoint-1.0.0
          type: string
        version:
          example: v1
          type: string
        md5:
          example: 36583a6a249b410e7fc4f892029709cac09763ddb230e1a829d5f9134d1abd07
          type: string
      title: The Service Info object
      type: object
    ServiceSchema:
      properties:
        serviceMetadata:
          $ref: '#/components/schemas/Service'
        definitionFile:
          format: binary
          type: string
        inlineContent:
          description: Inline content of the document
          type: string
      required:
      - serviceMetadata
      title: The Service Schema object
      type: object
    Settings:
      example:
        scopes:
        - service_catalog:service_view
        - service_catalog:service_view
      properties:
        scopes:
          items:
            example: service_catalog:service_view
            type: string
          type: array
      title: SettingsDTO
    Error:
      properties:
        code:
          format: int64
          type: integer
        message:
          description: Error message.
          type: string
        description:
          description: |
            A detail description about the error message.
          type: string
        moreInfo:
          description: |
            Preferably an url with more details about the error.
          type: string
        error:
          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'
          type: array
      required:
      - code
      - message
      title: Error object returned with 4XX HTTP Status
      type: object
    ErrorListItem:
      properties:
        code:
          type: string
        message:
          description: |
            Description about individual errors occurred
          type: string
        description:
          description: |
            A detail description about the error message.
          type: string
      required:
      - code
      - message
      title: Description of individual errors that may have occurred during a request.
      type: object
    Pagination:
      example:
        next: next
        total: 10
        offset: 0
        previous: previous
        limit: 1
      properties:
        offset:
          example: 0
          type: integer
        limit:
          example: 1
          type: integer
        total:
          example: 10
          type: integer
        next:
          description: |
            Link to the next subset of resources qualified.
            Empty if no more resources are to be returned.
          type: string
        previous:
          description: |
            Link to the previous subset of resources qualified.
            Empty if current subset is the first subset returned.
          type: string
      title: Pagination
  securitySchemes:
    OAuth2Security:
      flows:
        password:
          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
          tokenUrl: https://localhost:9443/oauth2/token
      type: oauth2

