Alignment of SFTI with bLink API specification

[simonmeyerm]

Contact Details

simon.meyer@six-group.com

Issue category

Refinement

Issue description

This issue proposes cosmetic documentation and consistency updates for the SFTI Account API and Payment API to better align with bLink conventions. The changes are non functional and focus on terminology, headers, response codes and OpenAPI schema hygiene.

Issue reasoning

We maintain SFTI specs in multiple aligned variants which creates avoidable editorial overhead and release complexity when conventions differ. Harmonising with bLink reduces duplication, improves readability and lowers the risk of misunderstandings.

Request

The working group is asked to decide whether to adopt the proposed non functional alignment changes for the Account API and Payment API, covering terminology, headers, response codes and documentation formatting.
The changes will be listed one by one for review and any concerns or disagreements can be raised and will be considered:

AccountAPI

• info-section:
  • Update Server-Url to "account.common-api.ch/api/v6"
• paths:
  • Align Response Codes by adding 502 and 504 to all endpoints
• schemas:
  • OpenAPI 3.0 tooling raises a warning when a schema object contains a $ref plus sibling fields (for example description) because sibling values are ignored. Should we comment out the sibling descriptions to avoid this warning until we migrate to OpenAPI 3.1?
  • Add "#  The attribute currency can be omitted only for multicurrency accounts." to the description of schema AccountItem.currency
  • Replace all description signs ">" with "|"
• responses:
  • Move examples for "InvalidToken" and "ExpiredToken" to 401
• parameters:
  • Add pattern: ^[A-Za-z0-9-._#{}]{5,64}$) to header X-Correlation-ID
  • Adjust "cursor" description to:   description: | 
            An opaque string value used for pagination. Use the value returned in the X-Next-Cursor response header of the previous request to retrieve the next page of results. The cursor is server-defined and must not be interpreted, modified or constructed by Service Users.
• general:
  • Align terms client / server to Service User / Service Provider. This change would impact:
    • GET/transactions description
    • Headers: User-Agent, Client_Id, X_PSU-IP-Address, X-PSU-User-Agent, X-Correlation-ID

PaymentAPI

• info-section:
  • Update Server-Url to "account.common-api.ch/api/v6"
• paths:
  • Align Response Codes by adding 502 and 504 to all endpoints
  • Change Request Body description of endpoint "/iso20022/payments" from The "XML pain.001." to "Payment instruction details as defined by data model."
  • Add object content "format: binary" to endpoint /iso20022/payments/{submissionId}/status:
  • Should endpoint "GET/consents" be added to the specification?
• schemas:
  • OpenAPI 3.0 tooling raises a warning when a schema object contains a $ref plus sibling fields (for example description) because sibling values are ignored. Should we comment out the sibling descriptions to avoid this warning until we migrate to OpenAPI 3.1?
  • Adjust description for schema "PaymentCreditor" to "The name of the creditor of a payment. Restriction for payment type SEPA is 70 characters."
  • Adjust all descriptions with "unique identifier (UUID)" to "unique identifier"
• responses:
  • Adjust detail description of example "InvalidParameter" to "detail: Sent data could not be processed"
  • Move examples for "InvalidToken" and "ExpiredToken" to 401
• parameters:
  • Add pattern: ^[A-Za-z0-9-._#{}]{5,64}$) to header X-Correlation-ID
• general:
  • Align terms client / server to Service User / Service Provider. This change would impact:
    • GET/transactions description
    • Headers: User-Agent, Client_Id, X_PSU-IP-Address, X-PSU-User-Agent, X-Correlation-ID

Proposed change

<<<<<<< Section As-Is

========

>>>>>>> Section To-Be

Affected API's

Both

Code of Conduct

• I agree to follow this project's Contribution Guidelines