Deploying APIs for Australia

This document guides you with the assumption that you have set up the WSO2 Open Banking Identity and Access Management and API Management modules on separate servers. 

Updating the CDS Swagger file

If you are deploying the  Consumer Data Standards API v1.3.0 API, do the following updates before you publish the API:

1. Open the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/1.3.0/consumer-data-standards-1.3.0.yaml Swagger file in a text editor.
2. To validate the x-fapi-auth-date for a valid HTTP-date:
   1. Locate all the - name: x-fapi-auth-date occurrences.

   2. Under each of these occurrences, add the following attribute: 

      pattern: '^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$'

3. To accept null or a JSON object as the Meta attribute in the POST request body:
   1. Locate the Meta attribute definition

   2. Add the following x-nullable and additionalProperties tags under the Meta attribute: 

      Meta:
         type: object
         x-nullable: true
         additionalProperties: {}

4. To validate the newest-time and the oldest-time query parameters passed in the GET Transactions for Account requests:

   1. Locate all the - name: oldest-time and - name: newest-time occurrences.

   2. Add the format: date-time tag under each occurrence as follows:

      - name: newest-time
        in: query
        description: Constrain the transaction history request to transactions with effective time at or before this date/time.  If absent defaults to today.  Format is aligned to DateTimeString common type
        required: false
        type: string
        format: date-time
        x-cds-type: DateTimeString

5. To enforce page and page-size query parameter validations.

   This is available only as a WUM update and is effective from April 20, 2021 (04-20-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products .

    Click here to see how it is done...

   Add the following tags in all CDS endpoints that expect  page and page-size as optional parameters:

   1. Before you deploy the API, open the Swagger file in a text editor.
   2. For example, let's consider the GET /banking/accounts endpoint where the page and page-size query parameters are optional. 
   3. Locate the GET /banking/accounts endpoint and its page tag.
   4. Locate the GET /banking/accounts endpoint and its page tag.

   5. Under the page tag add a new tag, named  minimum and define a minimum value.  For example: 

      - name: page
        in: query
        description: Page of results to request (standard pagination)
        required: false
        type: integer
        minimum: 1
        default: 1
        x-cds-type: PositiveInteger      

   6. Locate the page-size tag of the endpoint and define minimum and maximum values for the page size. For example:  

      - name: page-size
        in: query
        description: Page size to request. Default is 25 (standard pagination)
        required: false
        type: integer
        minimum: 1
        maximum: 1000
        default: 25
        x-cds-type: PositiveInteger

   7. Follow the above samples and update all required endpoints by defining limits for page and page-size values.
6. To validate min-amount and max-amount for AmountString:
   1.  Locate the min-amount and max-amount tags

   2. Add the following attribute under each tag: 

      pattern: '^\-?\d{1,16}\.\d{2,}$'

      For example:

      name: min-amount
      in: query
      description: Filter transactions to only transactions with amounts higher or equal to than this amount
      required: false
      type: string
      pattern: '^-?\d{1,16}.\d{2,}$'
      x-cds-type: AmountString
      
      name: max-amount
      in: query
      description: Filter transactions to only transactions with amounts less than or equal to than this amount
      required: false
      type: string
      pattern: '^-?\d{1,16}.\d{2,}$'
      x-cds-type: AmountString

7. Save the changes and publish the updated Swagger file.

Configuring the velocity_template.xml 

• Open the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file.
• Update the < IAM_HOSTNAME> placeholder with the hostname of your Identity and Access Management server.

Configuring synapse files 

Add the following synapse configurations to retrieve infosec statistics via the Consumer Data Standards Administration API.

1. Go to the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/ directory.
2. Open the following files and update them by adding the given property and handlers:
   
   1. _TokenAPI_.xml
   2. _RevokeAPI_.xml
   3. _AuthorizeAPI_.xml

3. Add the following property just under the <inSequence> tag: 

   <property name="api.ut.backendRequestTime" expression="get-property('SYSTEM_TIME')"/>

4. Add the following two handlers just under the <handlers> tag: 

   <handler class="org.wso2.carbon.apimgt.gateway.handlers.common.APIMgtLatencyStatsHandler"/>
   <handler class="com.wso2.finance.open.banking.management.information.reporting.data.publisher.ReportingDataHandler"/>

   Step 5 and step 6 are available only as a WUM update and are effective from June 30, 2019 (06-30-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products .

5. Copy the <WSO2_OB_APIM_HOME>/repository/resources/finance/sequences/AU/_token_error_mediator_.xml file to the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences directory.

6. Modify the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file by adding the <sequence key="_token_error_mediator_"/> tag as follows:

   <api
   	xmlns="http://ws.apache.org/ns/synapse" name="_WSO2AMTokenAPI_" context="/token">
   	<resource methods="POST" url-mapping="/*" faultSequence="_token_fault_">
   		<inSequence>
   			<property name="uri.var.portnum" expression="get-property('keyManager.port')"/>
   			<property name="uri.var.hostname" expression="get-property('keyManager.hostname')"/>
   			<send>
   				<endpoint>
   					<http uri-template="https://{uri.var.hostname}:{uri.var.portnum}/oauth2/token">
   						<timeout>
   							<duration>60000</duration>
   							<responseAction>fault</responseAction>
   						</timeout>
   					</http>
   				</endpoint>
   			</send>
   		</inSequence>
   		<outSequence>
   			<sequence key="_token_error_mediator_"/>
   			<send/>
   		</outSequence>
   	</resource>
   	<handlers>

Create and publish an API

In WSO2 Open Banking you can configure the following APIs:

• Consumer Data Standards API v1.3
• Consumer Data Standards Administration API v1.2.0
• CDR Arrangement Management API v1.0.0
• Dynamic Client Registration API v0.1

Follow the steps given below to create and publish an API.

You can configure APIs through the API Publisher by signing in as a user whose role includes  Internal/publisher . Follow the steps given below

1. Sign in to the API Publisher Portal (https://<WSO2_OB_APIM_HOST>:9443/publisher).
   

2. In the APIs tab, select CREATE NEW API > I Have an Existing REST API. 

   

3. Set the Input Type to OpenAPI File. 
   
4. Click BROWSE FILE TO UPLOAD and select the Swagger definition (.yaml file) from the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/consumerdatastandards.org.au/ directory based on your specification and version of the API.
   
5. Click Next. 

6. Set the endpoint according to your API. 

   Following services are available in the solution, update the <WSO2_OB_APIM_HOST> placeholder with the hostname of your API Manager server.

   API	Endpoint
   Consumer Data Standards API	https://<WSO2_OB_APIM_HOST>:9443/api/openbanking/backend-cds/services
   Consumer Data Standards Administration API	https://<WSO2_OB_APIM_HOST>:9443/api/openbanking/cds-admin-api/au100
   Dynamic Client Registration API	https://<WSO2_OB_APIM_HOST>:9443/api/openbanking/dynamic-client-registration/common
   CDR Arrangement Management API	https: //<WSO2_OB_IAM_HOST>:9446/cdr-arrangement-management/arrangements

7. Set the business plan to Unlimited : Allows unlimited   requests unless you want to limit the requests. 
   
8. Click Create to create the API.
9. Once you get the message that the API is successfully updated, go to Runtime Configurations using the left menu panel.
   
10. Click the edit button under Request > Message Mediation. 
    
11. Now, select the Custom Policy option.
12. Upload the relevant in-sequence file and click SELECT. For more details, see the table below. 
    
13. Scroll down and click SAVE.
14. Now, go to Properties using the left menu panel.
    
15. Click Add New Property.
    

16. Add the API Properties according to your API and click  the Add button. 

    API	Property Name	Property Value
    Consumer Data Standards API v1.3	ob-spec	au
    	ob-api-type	account
    Consumer Data Standards Administration API v1.2.0	ob-spec	au
    	ob-api-type	cds-admin
    Dynamic Client Registration API v0.1	ob-spec	au
    	ob-api-type	dcr
    CDR Arrangement Management API v1.0.0	ob-spec	au
    	ob-api-type	cdr-arrangement

    For example: 

    
    
    For more details, see the table below.

17. Click SAVE.
18. Go back to Overview using the left menu panel. 
    
19. Click PUBLISH.
    
20. The published API is available in the Developer Portal at https://<WSO2_OB_APIM_HOST>:9443/devportal .

Summarized information for configuring APIs

Enable endpoint versioning

When publishing the swagger, the Data Holder should edit each endpoint and include the supported endpoint versions in the x-version parameter as comma-separated values. For example:

 x-version: "1,2"

If you modify the Swagger after publishing the API, you need to republish the API to apply the changes. 

• To define a Data Holder specific identifier for extended API endpoints, configure the following. For example, if the Data Holder is ABC-Bank. 

  [open_banking.au]
  holder_identifier = "ABC-Bank"

Create a new version for an existing API

In the API Publisher of WSO2 Open Banking, users are not allowed to duplicate the scope of an API. Therefore, users are allowed to create a new version of the API in order to share the same scope. 

1. Sign in to the API Publisher at https://<WSO2_OB_APIM_HOST>:9443/publisher.

2. Navigate to the API listing page, and select the API for which you want to create a new version.

3. Click Create New Version.

   

4. Enter a version number and click Create.
   

5. You are redirected to the API Overview page.

6. Go to API Definition using the left menu panel.
   
7. Click IMPORT DEFINITION.
   

8. Set the Input Type to OpenAPI File.

9. Click BROWSE FILE TO UPLOAD and select the Swagger definition (.yaml file) according to your API.

10. Click Import. The changes are auto-saved.

11. Go to Runtime Configurations using the left menu panel.
    
12. Click the edit button under Request > Message Mediation. 
13. Now, select the Custom Policy option.
14. Upload the relevant in-sequence file and click SELECT. 
15. Scroll down and click SAVE.

16. Go to Lifecycle using the left menu panel.

    
17. Check Deprecate old versions after publishing the API checkbox, if you want to deprecate previous versions.
    

18. Check Requires re-subscription when publishing the API checkbox, only if you want to remove the subscriptions from the previous version. 

    Leave the Requires Re-Subscription when publishing the API checkbox cleared if you want all users who are subscribed to the older version of the API to be automatically subscribed to the new version. If not, they need to subscribe to the new version again.

19. Click  Publish .

Request payload validation

Request payload validation adds flexibility to validate an incoming request against any customisations done to the swagger definition.

For example, the x-v header in the CDS Banking API is a mandatory header and the solution will validate the incoming request against the published swagger. If the x-v header is not available in the requests the solution will give an error response. 

When you modify Swagger  the solution will validate the incoming request against the updated Swagger file. If you modify the Swagger after publishing the API, republish the API to apply the swagger based validations.  Therefore, follow the steps below:

Follow the instructions below to modify the sequence files and update the error responses of the Accounts API according to the CDS specification. 

1. Go to the <WSO2_OB_APIM_HOME>/repository/resources/finance/sequences/AU directory and locate the following files:
   • fault_error_mediator.xml
   • main_error_mediator.xml
   • common_error_mediator.xml
2. Copy the above files to the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences directory.
3. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/fault.xml file in a text editor.

   1. Find the <sequence key="_cors_request_handler_"/> tag and add the following property and sequence configurations:

      <property name="last_error_mediator" value="fault"/>
      <sequence key="_cors_request_handler_"/>
      <sequence key="_fault_error_mediator_"/>

   2. Save the changes. 
4. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/main.xml file in a text editor.

   1. Find the <send/> tag and add the following sequence configuration:

      <sequence key="_main_error_mediator_"/>
      <send/>

   2. Save the changes. 
5. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/_cors_request_handler_.xml file in a text editor.

   1. Find the </sequence> tag and add the following sequence configuration:

      <sequence key="_common_error_mediator_"/>
      </sequence>

   2. Save the changes. 
6. Restart the API Manager server.