explanation improvements (#73)

* Endpoint documentation improvements * AIS - Adjustment in the description of the usage for /balance and /transactions
swissfintechinnovations · Jan 22, 2024 · 8b8e83d · 8b8e83d
1 parent a79a79e
commit 8b8e83d
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 30 deletions.
diff --git a/accountAPI.yaml b/accountAPI.yaml
@@ -25,10 +25,9 @@ security:
 
 tags:
   - name: accounts
-    description: |
-      **Account Information**
-      Account Information Service - third party access to bank account data.
+    description: Third party access to bank account service considering account information and transaction data operations (JSON).
   - name: iso20022
+    description: Third party access to bank account service considering camt.053 operations (XML).
 
 paths:
   /accounts:
@@ -79,7 +78,7 @@ paths:
       tags:
         - accounts
       summary: Retrieve information about a single specific account
-      description: Return the accounts details of the requested account.
+      description: Returns the accounts details of the specified account.
       parameters:
         - $ref: '#/components/parameters/path_accountId'
         - $ref: '#/components/parameters/authorization_in_header'
@@ -91,7 +90,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: Account details of the requested account.
+          description: Account details of the specified account.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
@@ -122,10 +121,9 @@ paths:
         - accounts
       summary: Retrieve account balance information
       description: |
-        Account data of the specified account.
-        * Returns the intraday booked balance (ITBD), if called without a date.
-        * Returns the closing booked balance (CLBD), if called for a past date. In case the
-        specified day has not yet been finalized, the response will be a 404 error.
+        Returns account balance information of the specified account.
+        * Returns the intraday booked balance (ITBD) for the current day, if called without a date.
+        * Returns the closing booked balance (CLBD) for a specific day, if called for a past date (i.e. the closing booked balance (CLBD) of that day). In case the specified day has not yet been finalized, the response code will be 202.
       parameters:
         - $ref: '#/components/parameters/authorization_in_header'
         - $ref: '#/components/parameters/path_accountId'
@@ -138,7 +136,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: Account details of the requested account.
+          description: Account balance information of the specified account.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
@@ -173,10 +171,9 @@ paths:
         - accounts
       summary: Retrieve transactions of a specific account
       description: |
-        Transactions to and from the specified account.
+        Returns the transaction list of the specified account. Only postings with status booked will be returned.
         * Returns the transaction list of the current day, if called without a date.
-        * Returns the transaction list for a specific day, if called for a past date.
-        In case the specified day has not yet been finalized, the response will be a 404 error.
+        * Returns the transaction list for a specific day, if called for a past date (i.e. all transactions from that day). In case the specified day is not yet finalized, the response code will be 202.
       parameters:
         - $ref: '#/components/parameters/authorization_in_header'
         - $ref: '#/components/parameters/path_accountId'
@@ -283,9 +280,9 @@ paths:
     get:
       tags:
         - iso20022
-      summary: Retrieve a list of resource links to account statements (CAMT.053)
+      summary: Retrieve a list of resource links to account statements (camt.053)
       description: >
-        Get the resources links to available account statements (CAMT.053).
+        Get the resources links to available account statements (camt.053).
         The returned account statements must be conform to the XML schema and
         implementation guidelines defined by Swiss Payment Standards.
       parameters:
@@ -298,7 +295,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: Returns a list of resource links to ISO20022 XML CAMT.053 messages.
+          description: Returns a list of resource links to ISO20022 XML camt.053 messages.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
@@ -329,7 +326,7 @@ paths:
     get:
       tags:
         - iso20022
-      summary: Retrieves the designated ISO20022 XML CAMT.053 document.
+      summary: Retrieves the designated ISO20022 XML camt.053 document.
       parameters:
         - $ref: '#/components/parameters/path_reportId'
         - $ref: '#/components/parameters/authorization_in_header'
@@ -341,7 +338,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: Returns the requested ISO20022 XML CAMT.053 message.
+          description: Returns the requested ISO20022 XML camt.053 message.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
@@ -1041,7 +1038,7 @@ components:
     path_reportId:
       name: reportId
       in: path
-      description: Unique ID of the requested ISO20022 XML CAMT.053 document.
+      description: Unique ID of the requested ISO20022 XML camt.053 document.
       required: true
       schema:
         maxLength: 35

diff --git a/paymentAPI.yaml b/paymentAPI.yaml
@@ -24,12 +24,13 @@ security:
       - write
 tags:
   - name: standing orders
+    description: Third party payment service considering standing order operations (JSON).
   - name: payments
-    description: |
-      **Payment Initiation Submission**
-      Payment Submission Service - third party payment instruction submission
+    description: Third party payment service considering bulk payments operations (JSON). PUT operation can be used for both payment submission and payment initiation (PSS/PIS), depending on security implementation.
   - name: single payments
+    description: Third party payment service considering single payments operations (JSON). PUT operation can be used for both payment submission and payment initiation (PSS/PIS), depending on security implementation.
   - name: iso20022
+    description: Third party payment service considering pain.001 and pain.002 operations (XML). PUT operation can be used for both payment submission and payment initiation (PSS/PIS), depending on security implementation.
 
 paths:
   /standing-orders:
@@ -672,8 +673,8 @@ paths:
     post:
       tags:
         - iso20022
-      summary: Submit ISO20022 XML payment instruction (PAIN.001)
-      description: Submit an XML PAIN.001 payment instruction according to the ISO20022 specification.
+      summary: Submit ISO20022 XML payment instruction (pain.001)
+      description: Submit an XML pain.001 payment instruction according to the ISO20022 specification.
       parameters:
         - $ref: '#/components/parameters/authorization_in_header'
         - $ref: '#/components/parameters/clientid_in_header'
@@ -683,7 +684,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_ip_in_header'
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       requestBody:
-        description: The XML PAIN.001.
+        description: The XML pain.001.
         required: true
         content:
           application/xml:
@@ -718,7 +719,7 @@ paths:
     get:
       tags:
         - iso20022
-      summary: Retrieve a submitted ISO20022 XML PAIN.001 message
+      summary: Retrieve a submitted ISO20022 XML pain.001 message
       parameters:
         - $ref: '#/components/parameters/path_submissionId'
         - $ref: '#/components/parameters/authorization_in_header'
@@ -730,7 +731,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: Returns the requested ISO20022 XML PAIN.001 message.
+          description: Returns the requested ISO20022 XML pain.001 message.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
@@ -770,12 +771,12 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: ISO20022 XML PAIN.001 message submission has been deleted.
+          description: ISO20022 XML pain.001 message submission has been deleted.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
         '201':
-          description: ISO20022 XML PAIN.001 message submission is marked for deletion.
+          description: ISO20022 XML pain.001 message submission is marked for deletion.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'
@@ -813,7 +814,7 @@ paths:
         - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
       responses:
         '200':
-          description: Returns the requested ISO20022 XML PAIN.002 message.
+          description: Returns the requested ISO20022 XML pain.002 message.
           headers:
             X-Correlation-ID:
               $ref: '#/components/headers/X-Correlation-ID'