openapi: 3.0.0
info:
  description: |-
    Open Resource Discovery (ORD) is a protocol that standardizes how applications and services publish and discover their exposed resources such as APIs and Events.

    This API is an implementation of the [ORD Provider API](../index.md#ord-provider-api).
  version: 1.13.0
  title: Open Resource Discovery Document API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  # Replace this with the more specific API contact details:
  contact:
    email: info@sap.com
    name: SAP SE
    url: https://www.sap.com/
externalDocs:
  description: "Open Resource Discovery Specification"
  url: "https://open-resource-discovery.org"
tags:
  - name: OpenResourceDiscovery
servers:
  - url: https://ord-reference-application.cfapps.sap.hana.ondemand.com/
x-sap-api-type: "REST"
x-sap-shortText: "Implementation of the Open Resource Discovery 1.x Service Provider Interface"
x-sap-stateInfo:
  state: Active
paths:
  /.well-known/open-resource-discovery:
    get:
      summary: Get the Open Resource Discovery .well-known configuration
      description: |-
        This endpoint provides a [Well-Known URI](https://tools.ietf.org/html/rfc8615#section-3) discovery mechanism.
        It must be used for endpoint and capability discovery
      operationId: getConfiguration
      tags:
        - OpenResourceDiscovery
      responses:
        "200":
          description: Open Resource Discovery .well-known Configuration
          content:
            application/json:
              schema:
                type: object
                description: Open Resource Discovery Configuration schema object
        "304": # This response only needs to be included in case of the optional ETag 304 (Not Modified) support
          $ref: "#/components/responses/304"
        "401": # This response only needs to be included if the endpoint implements authorization
          $ref: "#/components/responses/401"
        "403": # This response only needs to be included if the endpoint implements authorization
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"

  # Fetch an ORD Document.
  # Please note that this path here is just a suggestion and could be implemented differently
  # Each document that is made available MUST be mentioned in the ORD .well-known configuration response.
  /open-resource-discovery/v1/documents/{id}:
    get:
      summary: |-
        Get an ORD Document
      description: |-
        This operation will retrieve a complete ORD Document with the given name / id.
      operationId: getDocument
      tags:
        - OpenResourceDiscovery
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ORD Document ID / name
      responses:
        "200":
          description: Open Resource Discovery Document
          content:
            application/json:
              schema:
                type: object
                description: Open Resource Discovery Document schema object
        "304": # This response only needs to be included in case of the optional ETag 304 (Not Modified) support
          $ref: "#/components/responses/304"
        "401": # This response only needs to be included if the endpoint implements authorization
          $ref: "#/components/responses/401"
        "403": # This response only needs to be included if the endpoint implements authorization
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
components:
  responses:
    "304":
      description: Not Modified
    "401":
      description: Unauthorized - Action requires user authentication.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            response:
              value:
                error:
                  code: UNAUTHORIZED
                  message: To access the API, you have to login
    "403":
      description: User or client is not authorized to perform the requested operation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            response:
              value:
                error:
                  code: FORBIDDEN
                  message: User or client is not authorized to perform the requested operation.
    "404":
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            response:
              value:
                error:
                  code: NOT_FOUND
                  message: >-
                    Requested resource not found.
    "500":
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            response:
              value:
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: >-
                    Internal server error occurred, retry after some time.
                    In case the issue persists contact your system administrator.
  schemas:
    ErrorResponse:
      type: object
      title: Error
      properties:
        error:
          $ref: "#/components/schemas/Error"
    Error:
      type: object
      title: Error Item
      properties:
        code:
          type: string
          title: Technical code of the error situation to be used for support purposes
        message:
          type: string
          title: User-facing (localizable) message, describing the error
        target:
          type: string
          title: Describes the error related data element (e.g. using a resource path)
        details:
          type: array
          title: Error Details
          items:
            $ref: "#/components/schemas/DetailError"
      additionalProperties: true
      required:
        - code
        - message
    DetailError:
      type: object
      title: Detail Error
      description: Error data that can be placed in the ErrorItem.details array
      properties:
        code:
          type: string
          title: Technical code of the error situation to be used for support purposes
        message:
          type: string
          title: User-facing (localizable) message, describing the error
      additionalProperties: true
      required:
        - code
        - message