Release of Platform v3

Welcome to the release notes of the new major version of the Platform API on bLink!

This release is the result of extensive discussions within the bLink community in order to streamline the information of the bLink directory and improve the usability of the API. Here you can find all relevant information about the updates, improvements and new features introduced in this version.

Release

• XE: 06/2024
• XP/Prod: 11/2024

Added

• Response code standard503 added to all endpoints
• Property companyNameAbbreviation added to schema directoryParticipantItem
• Property icon added to schema directoryParticipantItem
• Value ICON added to Enum directoryEmbedAssetType
• Property productName and productInfoUrl added to schema directoryParticipantItem
• Pagination added to API
  • New Parameter offset with default value 0 added
  • New Parameter limit with default value 20 added
  • New schemas pagedDirectoryClientItems and pagedDirectoryProviderItems with new property pagination added to response of endpoints GET/directory/clients and GET/directory/providers

Changed

• Schema directoryImageReference changed to directoryImage
  • Properties assetId and mimeType removed
  • Pattern of value changed to include mimetype inline
• Properties companyLogo in directoryParticipantItem changed to logo
• Property software in schema directoryParticipantItem removed
• Schema directorySoftwareDescription removed

Removed

• Property marketingImage in schema directoryParticipantItem removed
• Endpoint GET/assets/{assetId} removed
• Parameter path_assetId removed
• Redundant Header-Declarations optional_authorization_in_header, targetid_in_header, psu_ip_in_header, psu_user_agent_in_header and optional_correlation_in_header removed
• Response code standard405 removed

Changes in YAML

paths:
  /directory/clients:
    ...
      parameters:
        - $ref: '#/components/parameters/query_participant_status'
        - $ref: '#/components/parameters/query_embed_asset_type'
-       - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
+       - $ref: '#/components/parameters/offset'
+       - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of clients
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
-               type: array
-               items:
-                 $ref: '#/components/schemas/directoryClientItem'
+               $ref: '#/components/schemas/pagedDirectoryClientItems'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
-       '405':
-         $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
+       '503':
+         $ref: '#/components/responses/standard503'

  /directory/clients/{clientId}:
    ...
      parameters:
        - $ref: '#/components/parameters/path_clientId'
        - $ref: '#/components/parameters/query_embed_asset_type'
-       - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        ...
        '404':
          $ref: '#/components/responses/standard404'
-       '405':
-         $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
+       '503':
+         $ref: '#/components/responses/standard503'

  /directory/providers:
    ...
      parameters:
        - $ref: '#/components/parameters/query_participant_status'
        - $ref: '#/components/parameters/query_embed_asset_type'
-       - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
+       - $ref: '#/components/parameters/offset'
+       - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of providers
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
-               type: array
-               items:
-                 $ref: '#/components/schemas/directoryProviderItem'
+               $ref: '#/components/schemas/pagedDirectoryProviderItems'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
-       '405':
-         $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
+       '503':
+         $ref: '#/components/responses/standard503'

  /directory/providers/{providerId}:
    ...
      parameters:
        - $ref: '#/components/parameters/path_providerId'
        - $ref: '#/components/parameters/query_embed_asset_type'
-       - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      responses:
        '200':
          description: Information for a provider
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directoryProviderItem'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
-       '405':
-         $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
+       '503':
+         $ref: '#/components/responses/standard503'

- /assets/{assetId}:
-   get:
-     tags:
-       - directory
-       - asset
-       - image
-     summary: Retrieve assets for participants
-     description: |
-       Returns logo- and marketing images/assets for a participant (SCOPE: SIX)
-     operationId: retrieveAssets
-     parameters:
-       - $ref: '#/components/parameters/path_assetId'
-       - $ref: '#/components/parameters/optional_authorization_in_header'
-       - $ref: '#/components/parameters/correlation_in_header'
-       - $ref: '#/components/parameters/agent_in_header'
-       - $ref: '#/components/parameters/optional_instance_id_in_header'
-     responses:
-       '200':
-         description: Asset for the participant (image)
-         headers:
-           X-Correlation-ID:
-             $ref: '#/components/headers/X-Correlation-ID'
-           X-CorAPI-Source:
-             $ref: '#/components/headers/X-CorAPI-Source'
-         content:
-           image/svg+xml:
-             schema:
-               type: string
-               format: binary
-           image/png:
-             schema:
-               type: string
-               format: binary
-       '400':
-         $ref: '#/components/responses/standard400'
-       '401':
-         $ref: '#/components/responses/standard401'
-       '403':
-         $ref: '#/components/responses/standard403'
-       '404':
-         $ref: '#/components/responses/standard404'
-       '405':
-         $ref: '#/components/responses/standard405'
-       '500':
-         $ref: '#/components/responses/standard500'
-       '501':
-         $ref: '#/components/responses/standard501'

  /healthcheck:
    get:
      tags:
        - diagnostics
      summary: Returns all specified request headers and additional diagnostic information
      operationId: healthCheckGet
      parameters:
-       - $ref: '#/components/parameters/optional_authorization_in_header'
-       - $ref: '#/components/parameters/optional_correlation_in_header'
+       - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/optional_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
        ...
    post:
      ...
      parameters:
-       - $ref: '#/components/parameters/optional_authorization_in_header'
-       - $ref: '#/components/parameters/optional_correlation_in_header'
+       - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/optional_agent_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'

  /routinginstructions:
    get:
      tags:
        - routinginstructions
-     summary: Returns instructed routes for service user to service provider communication
+     summary: instructed routes per communication
+     description: Returns instructed routes for service user to service provider communication
      operationId: routingInstructions
      parameters:
-       - $ref: '#/components/parameters/optional_authorization_in_header'
-       - $ref: '#/components/parameters/optional_correlation_in_header'
+       - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/optional_agent_in_header'
-       - $ref: '#/components/parameters/optional_instance_id_in_header'

components:
  parameters:
    # bLink specific parameters
    path_clientId:
      ...
-   path_assetId:
-     name: assetId
-     in: path
-     description: id of assetId
-     required: true
-     schema:
-       maxLength: 36
-       type: string
    query_participant_status:
      name: status
      in: query
      description: |
        Returns clients or providers with the corresponding status.
-       Possible status: ACTIVE, ONBOARDING_DEVELOPMENT, INACTIVE, SUSPENDED
-       Default value when no matching status is found: ACTIVE
      schema:
        $ref: '#/components/schemas/directoryParticipantStatus'
    query_embed_asset_type:
      name: embed_assets
      in: query
      description: |
        ALL  = Embed all assets as base64
        LOGO = Embed all logos as base64
        NONE = No embedded assets
        Default value when no matching type is found: LOGO
      schema:
        $ref: '#/components/schemas/directoryEmbedAssetType'
-   optional_authorization_in_header:
-     name: Authorization
-     in: header
-     description: Bearer followed by a base64 encoded OAuth access token
-     required: false
-     schema:
-       type: string
-   targetid_in_header:
-     name: X-CorAPI-Target-ID
-     in: header
-     description: 'ID that identifies the provider (e.g., a Service Provider). (SCOPE: SIX required)'
-     required: true
-     schema:
-       type: string
-   psu_ip_in_header:
-     name: X-PSU-IP-Address
-     in: header
-     description: 'IP address of the user initiating the operation or AUTO for system triggered processes (SCOPE: SIX required)'
-     required: true
-     schema:
-       type: string
-   psu_user_agent_in_header:
-     name: X-PSU-User-Agent
-     in: header
-     description: 'User agent of the user initiating the operation or AUTO for system triggered processes (SCOPE: SIX required)'
-     required: true
-     schema:
-       type: string
+   offset:
+     name: offset
+     in: query
+     description: The number of items to skip before starting to collect the result set.
+     required: false
+     schema:
+       type: integer
+       minimum: 0
+       default: 0
+   limit:
+     name: limit
+     in: query
+     description: The number of items to return.
+     required: false
+     schema:
+       type: integer
+       minimum: 1
+       maximum: 100
+       default: 20
    correlation_in_header:
      name: X-Correlation-ID
      in: header
      description: Unique ID (defined by the caller) which will be reflected back in the response.
      required: true
      schema:
        type: string
        maxLength: 64
    agent_in_header:
      name: User-Agent
      in: header
      description: Name and version of the of the Client software
      required: true
      schema:
        type: string
    optional_agent_in_header:
      name: User-Agent
      in: header
      description: Name and version of the of the client software
      required: false
      schema:
        type: string
-   optional_correlation_in_header:
-     name: X-Correlation-ID
-     in: header
-     description: Unique ID (defined by the caller) which will be reflected back in the response.
-     required: false
-     schema:
-       type: string
-       maxLength: 64
    optional_instance_id_in_header:
      name: X-Instance-ID
      in: header
      description: '(Deprecated) Identifies an on-prem application instance which uses a legacy on-prem certificate in the mTLS connection. Do not use the header otherwise.'
      required: false
      schema:
        type: string
        maxLength: 64
    ...

headers:
  ...
  responses:
      ...
-   standard405:
-     headers:
-       Content-Type:
-         $ref: '#/components/headers/Content-Type'
-       Content-Language:
-         $ref: '#/components/headers/Content-Language'
-       X-Correlation-ID:
-         $ref: '#/components/headers/X-Correlation-ID'
-       X-CorAPI-Source:
-         $ref: '#/components/headers/X-CorAPI-Source'
-     description: Method Not Allowed
-     content:
-       application/problem+json:
-         schema:
-           $ref: '#/components/schemas/commonErrorResponse'

    standard500:
      ...

  schemas:
    # bLink specific schemas
    ## /directory
+   pagedDirectoryClientItems:
+     title: Paged Directory Client Items
+     type: object
+     properties:
+       data:
+         type: array
+         items:
+           $ref: '#/components/schemas/directoryClientItem'
+       pagination:
+         $ref: '#/components/schemas/pagination'

    directoryClientItem:
      title: Directory Client Item
      allOf:
        - required:
            - clientId
          type: object
          properties:
            clientId:
              type: string
              example: CIDX1234567890
        - $ref: '#/components/schemas/directoryParticipantItem'

+   pagedDirectoryProviderItems:
+     title: Paged Directory Provider Items
+     type: object
+     properties:
+       data:
+         type: array
+         items:
+           $ref: '#/components/schemas/directoryProviderItem'
+       pagination:
+         $ref: '#/components/schemas/pagination'

    directoryProviderItem:
      title: Directory Provider Item
      allOf:
        - required:
            - providerId
          type: object
          properties:
            providerId:
              type: string
              example: IIDX1234567890
        - $ref: '#/components/schemas/directoryParticipantItem'

    directoryParticipantItem:
      title: Directory Participant Item
      required:
-       - companyLogo
        - status
        - companyName
+       - companyNameAbbreviation
        - companyUrl
+       - productName
+       - productInfoUrl
        - contact
-       - marketingDescription
-       - shortDescription
-       - software
        - registrationDate
        - lastModified
      type: object
      properties:
        status:
          $ref: '#/components/schemas/directoryParticipantStatus'
        companyName:
          maxLength: 50
          type: string
          example: ACME
+       companyNameAbbreviation:
+         maxLength: 50
+         type: string
+         description: Abbreviation of company name for mobile applications
+         example: ACME
        companyUrl:
          type: string
          example: https://www.acme.com
-       marketingDescription:
-         $ref: '#/components/schemas/directoryMarketingDescription'
-       shortDescription:
-         $ref: '#/components/schemas/directoryShortDescription'
+       productName:
+         maxLength: 50
+         type: string
+         description: Product name of client
+         example: ACME accounting software
+       productInfoUrl:
+         type: string
+         example: https://acme.com/amce_accounting
+         description: Product Url of client
        contact:
          type: array
          example:
            - type: BUSINESS
              designation: Account and Payments Services
              emailAddress: business-contact@acme.com
            - type: TECHNICAL
              emailAddress: technical-contact@acme.com
              phone: +41 58 999 9999
            - type: SUPPORT
              emailAddress: support-contact@acme.com
              phone: +41 58 999 9997
          items:
            $ref: '#/components/schemas/directoryContact'
-       companyLogo:
-         $ref: '#/components/schemas/directoryMultisizeImageReference'
-       marketingImage:
-         $ref: '#/components/schemas/directoryImageReference'
+       logo:
+         $ref: '#/components/schemas/directoryImage'
+       icon:
+         $ref: '#/components/schemas/directoryImage'
        registrationDate:
          type: string
          format: date
          example: 2018-04-13
        lastModified:
          type: string
          format: date-time
          example: 2018-04-13T11:11:11Z
-       software:
-         $ref: '#/components/schemas/directorySoftwareDescription'
        useCases:
            ...

    directoryContact:
        emailAddress:
-         maxLength: 50
+         maxLength: 80
          type: string
          format: email
        ...

-   directorySoftwareDescription:
-     title: Directory Software Description
-     required:
-       - category
-       - manufacturer
-       - marketingDescription
-       - productInfoUrl
-       - productLogo
-       - productName
-       - shortDescription
-     type: object
-     properties:
-       productName:
-         $ref: '#/components/schemas/directoryProductName'
-       manufacturer:
-         maxLength: 50
-         type: string
-         example: ACME Corp.
-       category:
-         minItems: 1
-         type: array
-         example:
-           - ACCOUNTING
-         items:
-           type: string
-           enum:
-             - ACCOUNTING
-             - IT
-             - CRM
-       productInfoUrl:
-         type: string
-         example: https://acme.com/amce_accounting
-       productLogo:
-         $ref: '#/components/schemas/directoryMultisizeImageReference'
-       marketingImage:
-         $ref: '#/components/schemas/directoryImageReference'
-       marketingDescription:
-         $ref: '#/components/schemas/directoryMarketingDescription'
-       shortDescription:
-         $ref: '#/components/schemas/directoryShortDescription'

-   directoryMarketingDescription:
-     title: Directory Marketing Description
-     required:
-       - de
-       - en
-       - fr
-       - it
-     type: object
-     properties:
-       de:
-         type: array
-         items:
-           maxLength: 140
-           type: string
-       en:
-         type: array
-         items:
-           maxLength: 140
-           type: string
-       fr:
-         type: array
-         items:
-           maxLength: 140
-           type: string
-       it:
-         type: array
-         items:
-           maxLength: 140
-           type: string
-     example:
-       de:
-         - bullet1
-         - bullet2
-         - bullet3
-         - bullet4
-         - bullet5
-       en:
-         - bullet1
-         - bullet2
-         - bullet3
-         - bullet4
-         - bullet5
-       fr:
-         - bullet1
-         - bullet2
-         - bullet3
-         - bullet4
-         - bullet5
-       it:
-         - bullet1
-         - bullet2
-         - bullet3
-         - bullet4
-         - bullet5

-   directoryShortDescription:
-     title: Directory Short Description
-     required:
-       - de
-       - en
-       - fr
-       - it
-     type: object
-     properties:
-       de:
-         maxLength: 300
-         type: string
-       en:
-         maxLength: 300
-         type: string
-       fr:
-         maxLength: 300
-         type: string
-       it:
-         maxLength: 300
-         type: string
-     example:
-       de: Kurzbeschreibung
-       en: Short description
-       fr: Description rapide
-       it: Corta descrizione

    directoryUseCaseItem:
        ...
        properties:
          type: object
          additionalProperties:
            type: string
-       endpointInfos:
-         type: array
-         items:
-           $ref: '#/components/schemas/directoryEndpointInfo'

-   directoryProductName:
-     title: Directory Product Name
-     required:
-       - de
-       - en
-       - fr
-       - it
-     type: object
-     properties:
-       de:
-         maxLength: 50
-         type: string
-       en:
-         maxLength: 50
-         type: string
-       fr:
-         maxLength: 50
-         type: string
-       it:
-         maxLength: 50
-         type: string
-     example:
-       de: ACME Buchhaltungssoftware
-       en: ACME accounting software
-       fr: ACME software comptable
-       it: ACME software contabilità

-   directoryMultisizeImageReference:
-     title: Directory Multisize Image Reference
-     required:
-       - large
-       - small
-     type: object
-     properties:
-       small:
-         $ref: '#/components/schemas/directoryImageReference'
-       large:
-         $ref: '#/components/schemas/directoryImageReference'

    directoryParticipantStatus:
      title: Directory Participant Status
      type: string
      example: ACTIVE
      default: ACTIVE
      enum:
        - ACTIVE
        - INACTIVE
        - SUSPENDED
        - ONBOARDING_DEVELOPMENT

    directoryEmbedAssetType:
      title: Embed Asset Type
      type: string
-     example: LOGO
-     default: LOGO
+     example: ALL
+     default: ALL
      enum:
        - ALL
+       - ICON
        - LOGO
        - NONE

-   directoryImageReference:
-     title: Directory Image Reference
-     required:
-       - assetId
-       - mimeType
-     type: object
-     properties:
-       mimeType:
-         type: string
-         example: image/svg+xml
-       image:
-         pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
-         type: string
-         format: byte
-         example: QUNNRQ==
-       assetId:
-         type: string
-         format: string
-         example: assetId.svg

+   directoryImage:
+     title: Directory Image
+     type: string
+     pattern: '^data:image/svg\+xml;base64,[A-Za-z0-9+/]+=*$'
+     format: base64
+     example: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj4KICA8Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgc3R5bGU9ImZpbGw6cmVkOyIgLz4KPC9zdmc+Cg=='

    directoryEndpointInfo:
        ...

+   pagination:
+     type: object
+     properties:
+       totalCount:
+         type: integer
+         description: |
+           Total number of records, useful for pagination: use offset and limit parameters to query for any given page.
+           As long as the offset is less than totalCount, there will be records in the response. Once offset is larger
+           than totalCount, the response will be empty.
+         example: 100
+       offset:
+         type: integer
+         description: the offset which was requested in the query, or the default used by the server.
+         example: 0
+      limit:
+          type: integer
+         description: the limit which was requested in the query, or the default used by the server.
+         example: 20

    ## errors
    commonErrorResponse: