Deploying APIs for Berlin

This document guides you with the assumption that you have set up WSO2 Open Banking Key Manager, and WSO2 Open Banking API Manager in separate servers. 

Configuring the velocity_template.xml file

The <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file checks the deployed specification. It is by default configured to support berlin specification with the following handlers. 

Replace the <WSO2_OB_KM_HOST> placeholder with the hostname of your Open Banking Key Manager server.

#if($apiObj.additionalProperties.get("ob-spec") == "berlin")
## add ob-berlin specific handlers before the APIManagerExtensionHandler
<handler class="com.wso2.finance.open.banking.gateway.api.schema.validation.RequestSchemaValidationHandler"/>
<handler class="com.wso2.finance.open.banking.berlin.consent.enforcement.ConsentEnforcementHandler">
    <property name="accountValidationUrl" value="https://<WSO2_OB_KM_HOST>:9446/consent/berlin110/accounts-validation"/>
    <property name="keyStore" value="./repository/resources/security/wso2carbon.jks"/>
    <property name="password" value="wso2carbon"/>
    <property name="alias" value="wso2carbon"/>
</handler>
## end of Berlin-specific handlers
#end

Configuring the sequence file

The <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.3/dynamic-endpoint-insequence-1.3.3.xml file contains in sequences for accounts, payments and confirmation of funds APIs.

• The <WSO2_OB_KM_HOST> placeholders in this file need to be replaced by the hostname of your WSO2 Open Banking Key Manager server.

• The WSO2 Open Banking API Manager includes a mock bank backend which is configured by default in the in sequences. Ideally, the occurrences of https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/<API_NAME> should be replaced by the core banking system's API endpoints corresponding to the production and sandbox environments respectively. 

  For more information, see Integrating Core Banking System for Berlin

<sequence xmlns="http://ws.apache.org/ns/synapse" name="dynamic-endpoint-insequence-1.3.3.xml">
    <property name="endpointURI" expression="get-property('To')"/>

    <switch source="$ctx:endpointURI">
        <case regex=".*payments.*">
            <header name="TPP-Unique-ID" scope="transport" expression="get-property('api.ut.consumerKey')"/>
            <filter source="$ctx:endpointURI" regex=".*authorisations.*">
                <then>
                    <header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/authorisation"/>
                </then>
                <else>
                    <filter source="get-property('api.ut.HTTP_METHOD')" regex="POST">
                        <then>
                            <header name="To" value="https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/payments"/>
                            <filter source="$ctx:endpointURI" regex="^((?!\/bulk-payments).)*$">
                                <then>
                                    <payloadFactory media-type="json">
                                        <format>[$1]</format>
                                        <args>
                                            <arg evaluator="json" expression="$"/>
                                        </args>
                                    </payloadFactory>
                                </then>
                            </filter>
                        </then>
                        <else>
                            <property name="resourcePath" scope="default" type="STRING" value=""/>
                            <property expression="get-property('resourcePath')" name="REST_URL_POSTFIX" scope="axis2"
                                      type="STRING"/>

                            <header name="To"
                                    expression="fn:concat('https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/payments', get-property('api.ut.resource'))"/>
                        </else>
                    </filter>
                </else>
            </filter>
        </case>
        <case regex=".*/accounts.*">
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
                </then>
                <else>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
                </else>
            </filter>
        </case>
        <case regex=".*/card-accounts.*">
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
                </then>
                <else>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/accounts"/>
                </else>
            </filter>
        </case>
        <case regex=".*/consents.*">
            <filter source="$ctx:endpointURI" regex=".*authorisations.*">
                <then>
                    <header name="To" value="fn:concat('https://<WSO2_OB_KM_HOST>:9446/consent/berlin130/authorisation/accounts', get-property('api.ut.resource'))"/>
                </then>
                <else>
                    <property action="remove" name="REST_URL_POSTFIX" scope="axis2"/>
                    <header name="To" expression="fn:concat('https://<WSO2_OB_KM_HOST>:9446/consent/berlin130' , get-property('api.ut.resource'))"/>
                    <header name="TPP-Unique-ID" expression="get-property('api.ut.consumerKey')" scope="transport"/>
                    <header name="App-ID" expression="get-property('api.ut.application.id')" scope="transport"/>
                    <rewrite>
                        <rewriterule>
                            <action type="replace" regex="\/consents" value="\/accounts" fragment="path"/>
                        </rewriterule>
                    </rewrite>
                </else>
            </filter>
        </case>
        <case regex=".*/funds-confirmations.*">
            <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                <then>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/cof"/>
                </then>
                <else>
                    <header name="To" value="https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/cof"/>
                </else>
            </filter>
        </case>
    </switch>
    <property name="ENDPOINT_ADDRESS" expression="get-property('To')"/>
</sequence>

Configuring an API

WSO2 Open Banking Berlin has the NextGenPSD2XS2AFramework-1.3.3 API which contains the v1.3 resource for Accounts, Payments and Confirmation of Funds flows. The swagger definition for this API is available in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.3/psd2-api_1.3.3_20190412.yaml.

Given below is the procedure to configure and publish the NextGenPSD2XS2AFramework-1.3.3 API. 

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

   

2. Click ADD NEW API.

   

3. Select I Have an Existing API option.

   

4. Select the Swagger File option and browse for the swagger definition by clicking on the Browse button. Select the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.3/psd2-api_1.3.3_20190412.yaml file.

5. Click Start Creating.

6. You are directed to the Design API stage. Design General Details are loaded for you in the Design tab.

   You need to set the context value as xs2a

   
7. Click Next: Implement to navigate to the next level.
8. Expand Managed API, and set Endpoint Type by selecting Dynamic Endpoint from the drop-down list.
9. Check Select a message mediation policy to be executed in the message flow under Message Mediation Policies.

10. Click Upload In Flow and select the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.3/dynamic-endpoint-insequence-1.3.3.xml In sequence file.
    

11. Click Next: Manage to navigate to the next level.

12. Under Subscription Tiers, check the option Unlimited : Allows unlimited requests unless you want to limit the requests.
    

13. Expand API Properties and add the following as Additional properties. 

    Property Name	Property Value
    ob-spec	berlin
    ob-api-type	psd2

14. Click the + button to save the values.
    

15. Click Save & Publish.

16. The published API is available in the API Store at https://<WSO2_OB_APIM_HOST>:9443/store.

Summarized information for configuring APIs 

Create a new version for an existing API

1. In the API Publisher (https://<WSO2_OB_APIM_HOST>:9443/publisher), click the API thumbnail to view the API overview.
   

2. Select the CREATE NEW VERSION tab.

   

3. Follow the versioning format and define the new version.
   

4. Click Done.

   Define the correct version for the API and choose the swagger and In sequence files appropriately.

   The directory path to the files in the solution pack helps you to choose the correct file. For example, choose the swagger and in sequence files from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Accounts/3.1.0 if you want to create the 3.1.0 version of Payment Initiation API.

5. Select the newly created API and click EDIT API.
   
6. You are redirected to the Design phase. Click the Edit Source button under API Definition section.
   
7. In the Swagger Editor menu bar, select File>Import File.
8. Browse for the intended swagger file in .yaml format and click Open File.
9. Click Apply Changes to save the changes and go back to the Design page.
   
10. Scroll down and click Save.
11. Click Next: Implement > to navigate to the next page.
12. Expand Managed API, and click Upload In Flow.
13. Select the relevant In sequence file for the corresponding API and its version, and click Upload.
    
14. Click Next: Manage > to navigate to the next page.
15. Expand API Properties and ensure the ob-spec property is set to reflect the correct specification.

16. Click Save & Publish.

    To get the existing subscriptions to the new version, follow the steps below:

    1. In the API Publisher, click the new API thumbnail to Browse API.
       
    2. Go to the Lifecycle tab.
       Tick the relevant boxes if you want to:
       1. Deprecate the old versions after publishing this new version.
       2. Remove the existing subscriptions and require the applications to re-subscribe.
       
    3. Click Publish.
    4. To verify the subscriptions, go to the Versions tab.
       

Configure the FrequenyPerDay throttling policy

The FrequencyPerDay value is sent in the consent initiation request body to indicate the requested maximum frequency for access without PSU involvement per day. According to the NextGenPSD2 XS2A framework, the FrequencyPerDay value needs to be checked when the PSU's IP address is not sent in an API invocation request.

Use the below instructions to configure the FrequencyPerDay throttling policy:

1. Open <WSO2_OB_APIM_HOME>/repository/conf/api-manager.xml.

   1. Make sure that the throttling is enabled for Data Publisher under the <DataPublisher> attribute of <ThrottlingConfigurations>:

      <ThrottlingConfigurations>
      <DataPublisher>
      <Enabled>true</Enabled>

   2. Change the value of the <Username> attribute under <TrafficManager> according. By default, it looks as follows: 

      <!--Required in OB-->
      <Username>admin@wso2.com@carbon.super</Username>

   3. Change the value of te <connectionfactory.TopicConnectionFactory> attribute under <JMSConnectionParameters> according. By default, it looks as follows: 

      <JMSConnectionParameters>
      <!--Required in OB-->
      <connectionfactory.TopicConnectionFactory>amqp://admin!wso2.com!carbon.super:${admin.password}@clientid/carbon?brokerlist='tcp://${carbon.local.ip}:${jms.port}'</connectionfactory.TopicConnectionFactory>

2. Make sure that the FrequencyPerDay property is enabled in <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml as follows:

   <EnableFrequencyPerDay>true</EnableFrequencyPerDay>

3. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/<publisher-name>--NextGenPSD2XS2AFramework_v1.xml file and place CustomThrottlingPolicyHandler before ThrottleHandler as follows:

   <handler class="com.wso2.finance.open.banking.custom.throttling.CustomThrottlingPolicyHandler"/>
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.ThrottleHandler"/>

4. Deploy the throttling policy located in <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/wso2-obam-conf/FrequencyPerDayPolicy as
   a custom throttling policy in the admin portal of WSO2 Open Banking API Manager:

   1. Sign in to the Admin Portal using the URL (https://<WSO2_OB_APIM_HOST>:9443/admin) and your admin credentials.

   2. ClickThrottling Policies tab and click Custom Policies tab.

   3. Enter the information for the custom policy accordingly.

      • Name the custom policy as "FrequencyPerDayPolicy".
      • For Key Template, use the following format: $customProperty.accountId:$userId:$appId.
      • Copy the content from the policy in <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/wso2-obam-conf/FrequencyPerDayPolicy and paste it under Siddhi Query.

Request payload validation

Request payload validation adds flexibility to validate an incoming request against any customisations done to the swagger definition. For example, modify the currency property in the API swagger and then the solution will validate the incoming request against the updated currency value. Simply modify the published swagger file and republish the API for the modifications to take effect.

If you modify the Swagger after publishing the API, republish the API to apply the swagger based validations.