index.yaml

# Copyright 2020 - 2024 PeopleWare n.v.
#
# 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.1.0
info:
  title: ppwcode openapi demonstration
  description: >-
    Collection of common OpenAPI 3 specs
  version: 12.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: PeopleWare n.v.
    email: info@peopleware.be
    url: 'https://www.peopleware.be/'
servers:
  - url: 'https://www.ppwcode.org/openapi/common'
    description: Dummy endpoint. There is nothing here.
tags:
  - name: Immutable data
    x-traitTag: true
    description:
      $ref: 'resource/immutable.md'
  - name: Caching
    x-traitTag: true
    description:
      $ref: 'resource/caching.md'
  - name: Lists
    x-traitTag: true
    description:
      $ref: 'resource/paging.md'
  - name: Canonical and fully qualified URI
    x-traitTag: true
    description:
      $ref: 'string/canonical-and-fq-uri.md'
  - name: Determining the build number of service dependencies to interact with
    x-traitTag: true
    description:
      $ref: 'resource/determining-build-number.md'
  - name: Search and to-many associations
    x-traitTag: true
    description:
      $ref: 'resource/search-and-to-many-associations.md'
security:
  - OAuth2:
      - use
paths:
  /health:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'oauth2/authorization.yaml'
    get:
      summary: Health of the API
      description: >-
        Returns `200` when a superficial check of the API, service, and its resources says it is healthy. A `470` means
        the system is still reachable, but determines itself that it is not in good health. If the system is no longer
        reachable, or fatally hampered, expect a `500` or any other error.
      operationId: healthGet
      responses:
        '200':
          description: >-
            The service was reached, and it deemed itself healthy.
          headers:
            x-flow-id:
              required: true
              schema:
                $ref: 'id/UUID.yaml'
            x-mode:
              required: true
              schema:
                $ref: 'id/mode.yaml'
            cache-control:
              required: true
              schema:
                $ref: 'resource/cacheControlNoCache.yaml'
            # no vary necessary, because no-cache
            x-date:
              required: true
              schema:
                $ref: 'resource/date.yaml'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '470':
          description: >-
            The service was reached, but some of its dependencies are not healthy. The service should not be used.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getNoCache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health'
  /demonstration/{crn}/{label}/{persistenceId}:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'parameters/crn.yaml'
      - $ref: 'parameters/label.yaml'
      - $ref: 'parameters/persistenceId.yaml'
      - $ref: 'oauth2/authorization.yaml'
    get:
      summary: Demonstration of a list
      description: use of page control query parameters
      operationId: demonstrationList
      parameters:
        - $ref: 'parameters/at.yaml'
        - $ref: 'parameters/page.yaml'
        - $ref: 'parameters/perPage.yaml'
      responses:
        '200':
          x-summary: The page was found
          description: We get a list of references
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getPrivateDynamicAt'
          content:
            application/json:
              schema:
                type: object
                required:
                  - hrefs
                  - href
                properties:
                  hrefs:
                    type: array
                    items:
                      type: string
                      format: uri
                      example: ../a/reference?at=2021-01-19T17:14:18.482Z
                  href:
                    $ref: 'resource/PagingHref.yaml'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          x-summary: The requested page never existed, or did not exist yet at `at`
          description: >-
            Probably, the page that was requested was past the last page, i.e., the number of items in the list is less
            than or equal to `per_page * (page - 1)`. E.g., with 113 entries, the last page with `per_page = 20`, is
            page 6. A request for page 7 results in a `404`.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getPrivateDynamicAt'
    post:
      summary: Demonstration of common specs for `POST`
      description: Every common spec is mentioned here.
      operationId: demonstrationPost
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resource'
      responses:
        '201':
          x-summary: The resource was created with the given information
          description: Every common spec is mentioned here.  The `201` response shows `readOnly` properties.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/post201'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
  /demonstration/{crn}/{label}/{persistenceId}/{id}:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'parameters/crn.yaml'
      - $ref: 'parameters/label.yaml'
      - $ref: 'parameters/persistenceId.yaml'
      - $ref: 'oauth2/authorization.yaml'
      - name: id
        in: path
        description: id of the resource
        schema:
          $ref: 'id/UUID.yaml'
    get:
      summary: Demonstration of common specs for `GET`
      description: Every common spec is mentioned here.
      operationId: demonstrationGet
      parameters:
        - $ref: 'parameters/at.yaml'
      responses:
        '200':
          x-summary: The resource exists
          description: Every common spec is mentioned here.  The `200` response shows `readOnly` properties.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getPrivateDynamicAt'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          $ref: 'resource/404At.yaml'
    put:
      summary: Demonstration of common specs for `PUT`
      description: >-
        Every common spec is mentioned here. The request body does not show `readOnly` properties.
      operationId: demonstrationPut
      parameters:
        - $ref: 'parameters/optimisticLocking.yaml'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/resource'
      responses:
        '200':
          x-summary: The resource was updated
          description: Every common spec is mentioned here.  The `200` response shows `readOnly` properties.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/put'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/resource'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          $ref: 'resource/404Put.yaml'
        '412':
          x-summary: Optimistic locking failed
          description: >-
            The date-time provided in the request header `if-unmodified-since` was not the most recent for the resource.


            The body contains the most recent version of the resource, on which the client can base a retry.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/put'
          content:
            application/json:
              schema:
                # NOTE: replace with the correct schema
                $ref: '#/components/schemas/resource'
  /demonstration/{crn}/{label}/{persistenceId}/{id}/history:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'parameters/crn.yaml'
      - $ref: 'parameters/label.yaml'
      - $ref: 'parameters/persistenceId.yaml'
      - $ref: 'oauth2/authorization.yaml'
      - name: id
        in: path
        description: id of the resource
        schema:
          $ref: 'id/UUID.yaml'
    get:
      summary: Demonstration of common specs for `GET` resource history
      description: A list of the different times at which the resource's information was changed.
      operationId: demonstrationGetHistory
      responses:
        '200':
          x-summary: The resource exists
          description: >-
            A list of the different times at which the resource's information was changed, ordered from most to least
            recent, with links to retrieve that version of the information. Changes `< x-date` are included.


            This call does not use paging, because we expect less than 50 changes to the information of the resource.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getPrivateDynamic'
          content:
            application/json:
              schema:
                $ref: 'resource/History.yaml'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          $ref: 'resource/404Get.yaml'
  /demonstration/{crn}/{label}/{persistenceId}/{id}/search-document:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'parameters/crn.yaml'
      - $ref: 'parameters/label.yaml'
      - $ref: 'parameters/persistenceId.yaml'
      - $ref: 'oauth2/authorization.yaml'
      - name: id
        in: path
        description: id of the resource
        schema:
          $ref: 'id/UUID.yaml'
    get:
      summary: Demonstration of common specs for `GET` search document
      description: >-
        Document to be indexed by search engine. Deprecated. Please use version 2.
      operationId: demonstrationGetSearchDocument
      deprecated: true
      responses:
        '200':
          x-summary: The resource exists
          description: Versioned. Has a `href`.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getNoCache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchDocument'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          $ref: 'resource/404NoCache.yaml'
  /demonstration/{crn}/{label}/{persistenceId}/{id}/2/search-document:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'parameters/crn.yaml'
      - $ref: 'parameters/label.yaml'
      - $ref: 'parameters/persistenceId.yaml'
      - $ref: 'oauth2/authorization.yaml'
      - name: id
        in: path
        description: id of the resource
        schema:
          $ref: 'id/UUID.yaml'
    get:
      summary: Demonstration of common specs for `GET` search document
      description: Document to be indexed by search engine
      operationId: demonstrationGetSearchDocument2
      responses:
        '200':
          x-summary: The resource exists
          description: Versioned.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getNoCache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchDocument2'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          $ref: 'resource/404NoCache.yaml'
  /demonstration/search:
    parameters:
      - $ref: 'parameters/forceError.yaml'
      - $ref: 'parameters/flowId.yaml'
      - $ref: 'parameters/mode.yaml'
      - $ref: 'oauth2/authorization.yaml'
      - in: query
        name: searchTerm
        required: true
        description: >-
          Text to search for with a fuzzy search in all indexed fields. Trimmed.
        schema:
          type: string
          minLength: 1
        example: find%20me
      - $ref: 'parameters/page.yaml'
      - $ref: 'parameters/perPage.yaml'
    get:
      summary: Demonstration of fuzzy search
      description: >-
        Return links to resource that have something to do with `searchTerm`, and information for humans to recognize
        the found items.
      operationId: demonstrationGetSearchResults
      responses:
        '200':
          x-summary: The request page exists
          description: >-
            The found resources are returned with paging.
          headers:
            $ref: 'resource/CommonResponseHeaders.yaml#/getNoCache'
          content:
            application/json:
              schema:
                $ref: 'resource/SearchResults.yaml'
        '400':
          $ref: 'resource/400.yaml'
        '401':
          $ref: 'oauth2/401.yaml'
        '403':
          $ref: 'oauth2/403.yaml'
        '404':
          $ref: 'resource/404NoCache.yaml'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: Some OAuth2 authNZ
      flows:
        authorizationCode:
          authorizationUrl: https://api.example.com/oauth2/authorize
          tokenUrl: https://api.example.com/oauth2/token
          scopes:
            use: use the api
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          scopes:
            use: use the api
  schemas:
    health:
      allOf:
        - $ref: 'resource/StructureVersion1.yaml'
        - $ref: 'health/Health.yaml'
        - type: object
          required:
            - dependency
          properties:
            dependency:
              $ref: 'health/Status.yaml'
    resource:
      allOf:
        - $ref: 'resource/StructureVersion2.yaml'
        - $ref: 'resource/Audited.yaml'
        - type: object
          required:
            - location
            - href
          properties:
            human:
              type: object
              properties:
                gender:
                  $ref: 'human/Gender.yaml'
            id:
              type: object
              properties:
                naturalPerson:
                  type: object
                  properties:
                    be:
                      type: object
                      properties:
                        inss:
                          $ref: 'id/naturalPerson/be/INSS.yaml'
                legalPerson:
                  type: object
                  properties:
                    be:
                      type: object
                      properties:
                        crn:
                          $ref: 'id/legalPerson/be/CRN.yaml'
                sigedis:
                  type: object
                  properties:
                    sigedisId:
                      $ref: 'id/sigedis/SigedisId.yaml'
                    sigedisRegistrantId:
                      $ref: 'id/sigedis/SigedisRegistrantId.yaml'
                    sigedisRegistrantRegulationIdentification:
                      $ref: 'id/sigedis/SigedisRegistrantRegulationIdentification.yaml'
                uuid:
                  $ref: 'id/UUID.yaml'
                mode:
                  $ref: 'id/mode.yaml'
                accountId-readOnly:
                  $ref: 'id/AccountId.yaml'
            location:
              type: object
              properties:
                address:
                  $ref: 'location/Address.yaml'
                country:
                  $ref: 'location/Country.yaml'
            money:
              type: object
              properties:
                currencyCode:
                  $ref: 'money/CurrencyCode.yaml'
                monetaryValue:
                  $ref: 'money/MonetaryValue.yaml'
                negativeMonetaryValue:
                  $ref: 'money/NegativeMonetaryValue.yaml'
                nonPositiveMonetaryValue:
                  $ref: 'money/NonPositiveMonetaryValue.yaml'
                nonNegativeMonetaryValue:
                  $ref: 'money/NonNegativeMonetaryValue.yaml'
                positiveMonetaryValue:
                  $ref: 'money/PositiveMonetaryValue.yaml'
                baseMoneyAmount:
                  $ref: 'money/BaseMoneyAmount.yaml'
                moneyAmount:
                  $ref: 'money/MoneyAmount.yaml#/schema'
                monetaryValue2:
                  $ref: 'money/MonetaryValue2.yaml'
            oauth2:
              type: object
              properties:
                bearerAccessToken:
                  $ref: 'oauth2/BearerAccessToken.yaml'
                wwwAuthenticate:
                  $ref: 'oauth2/WWWAuthenticate.yaml'
            string:
              type: object
              properties:
                canonicalURI:
                  $ref: 'string/CanonicalURI.yaml'
                canonicalURIWithKnowledgeTime:
                  $ref: 'string/CanonicalURIWithKnowledgeTime.yaml'
                cleanedString:
                  $ref: 'string/CleanedString.yaml'
                language:
                  $ref: 'string/Language.yaml'
                relativeURI:
                  $ref: 'string/RelativeURI.yaml'
                telephoneNumber:
                  $ref: 'string/TelephoneNumber.yaml'
                trimmedString:
                  $ref: 'string/TrimmedString.yaml'
            number:
              type: object
              properties:
                decimal:
                  $ref: 'number/Decimal.yaml'
            time:
              type: object
              properties:
                dateTime:
                  $ref: 'time/DateTime.yaml'
                changeDateTime:
                  $ref: 'time/ChangeDateTime.yaml'
                dayDate:
                  $ref: 'time/DayDate.yaml'
                month:
                  $ref: 'time/Month.yaml'
                quarter:
                  $ref: 'time/Quarter.yaml'
                year:
                  $ref: 'time/Year.yaml'
                dayDateInterval:
                  $ref: 'time/DayDateInterval.yaml'
            readOnly:
              type: string
              readOnly: true
              description: >-
                `readOnly` properties only appear in responses, not in request bodies
              example: I am a read-only property
            href:
              allOf:
                - $ref: 'resource/HREFHistorySearchable.yaml'
                - example:
                    history: 123/history
                    searchDocument: 123/search-document
    searchDocument:
      allOf:
        - $ref: 'resource/SearchDocument.yaml'
        - type: object
          properties:
            content:
              allOf:
                - $ref: 'resource/SearchResultBase.yaml'
                - type: object
                  required:
                    - interestingInfo
                  properties:
                    interestingInfo:
                      type: string
                      minLength: 1
                      example: 'look what I‘ve found'
    searchDocument2:
      allOf:
        - $ref: 'resource/SearchDocument2.yaml'
        - type: object
          properties:
            content:
              allOf:
                - $ref: 'resource/SearchDocumentContentBase2.yaml'
                - type: object
                  required:
                    - interestingInfo
                  properties:
                    interestingInfo:
                      type: string
                      minLength: 1
                      example: 'look what I‘ve found'
    # Token requests bodies listed explicitly here as workaround for https://github.com/Redocly/redoc/issues/862#issuecomment-491631228
    # This is actually used in `money/MoneyAmount.yaml`.
    baseMinorUnit0:
      $ref: 'money/MoneyAmount.yaml#/components/schemas/baseMinorUnit0'
    baseMinorUnit2:
      $ref: 'money/MoneyAmount.yaml#/components/schemas/baseMinorUnit2'
    baseMinorUnit3:
      $ref: 'money/MoneyAmount.yaml#/components/schemas/baseMinorUnit3'
    baseMinorUnit4:
      $ref: 'money/MoneyAmount.yaml#/components/schemas/baseMinorUnit4'