This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Deploying APIs for Berlin

Owned by Former user (Deleted)
Last updated: Sept 07, 2022 by Former user (Deleted)Version comment
8 min read

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. 

 

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.

To return proper error messages when the transport certificate validation fail:

This is available only as a WSO2 Update and is effective from October 11, 2021 (10-11-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

  1. Open the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/TokenAPI.xml file.

  2. Add the following handler at the end of the existing handler chain. 

    <handler class="com.wso2.finance.open.banking.gateway.common.MTLSErrorValidationHandler"/>
  3. Save the change and restart the API Manager server.


Configuring sequence files

  • Go to the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/<API_Name>/<API_version> directory. 
  • Find the in sequence file of the API you wish to deploy.

  • Based on the port, update the references of the hostnames to the hostname of your servers.  

    Port number

    Update the local

    9443 Hostname of the API Management server
    9446 Hostname of the Identity and Access Management server

    For example, if the URL is  https://localhost:9446/api/openbanking/consent-mgt/berlin130/payments , it should be updated with the hostname of the Identity and Access Management server: 

    https://<WSO2_OB_IAM_HOST>:9446/api/openbanking/consent-mgt/berlin130/payments

    If you are using the following deployment options, update the placeholders as follows:

  • By default, a mock backend is configured in the in sequence files of the API Manager. The two endpoints should be replaced by the core banking system's API endpoints corresponding to the production and sandbox environments respectively. For more information on how to integrate a core banking system, see Integrating Core Banking System.

Update the Swagger file

  • Open the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.6/psd2-api_1.3.6_20200327.yaml file using a text editor.

  • Locate the maxItems: 11 property and list it below the type:array property.  

     Click here to see how an updated Swagger file... 
      monthsOfExecution:
      description: |
        The format is following the regular expression \d{1,2}.
        The array is restricted to 11 entries.
        The values contained in the array entries shall all be different and the maximum value of one entry is 12.
        This attribute is contained if and only if the frequency equals "MonthlyVariable".
        Example: An execution on January, April and October each year is addressed by ["1", "4", "10"].
      type: array
      maxItems: 11
      items:
        type: string
        maxLength: 2
        enum:
          - "1"
          - "2"
          - "3"
          - "4"
          - "5"
          - "6"
          - "7"
          - "8"
          - "9"
          - "10"
          - "11"
          - "12"
  • Save the changes.

Create and publish an API

In WSO2 Open Banking for Berlin, you can configure the following APIs:

  • Accounts API 
  • Payments API 
  • Confirmation of Funds API 

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

  • Create a user with Internal/creator and Internal/publisher roles in order to configure the API. For more information on creating a user, see Configuring users and roles.
  • If an API is already deployed with a previous version, you may create a new version of it instead of deploying a new API. For more information, see Create a new version for an existing 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 <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.6/psd2-api_1.3.6_20200327.yaml Swagger definition (.yaml file).
  5. Click Next. 
  6. Leave the Endpoint field empty as it is.

  7. Set the Context value as follows: 

    xs2a
  8. Set the business plan to Unlimited : Allows unlimited  requests unless you want to limit the requests. 
  9. Click Create to create the API.
  10. Once you get the message that the API is successfully updated, go to Runtime Configurations using the left menu panel.
  11. Click the edit button under Request > Message Mediation. 
  12. Now, select the Custom Policy option.
  13. Upload the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.6/dynamic-endpoint-insequence-1.3.6.xml file and click SELECT.   
  14. Scroll down and click SAVE.
  15. Go to  Endpoints using the left menu panel.
  16. Select Dynamic Endpoint. 
  17. Select the endpoint types; Production Endpoint/Sandbox Endpoint.
  18. Click Save.
  19. Now, go to Properties using the left menu panel.
  20. Click Add New Property.

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

    Property Name

    Property Value

    ob-specberlin
    ob-api-typepsd2

    For example: 

  22. Click SAVE.
  23. Go back to Overview using the left menu panel. 
  24. Click PUBLISH.
  25. The published API is available in the Developer Portal at https://<WSO2_OB_APIM_HOST>:9443/devportal.

Summarized information for configuring APIs

APISwagger definition (yaml file)Endpoint

Message mediation (sequence file)


API property nameAPI property value
NextGenPSD2 Framework Version 1.3.6<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.6/psd2-api_1.3.6_20200327.yamlDynamic Endpoint

<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.6/dynamic-endpoint-insequence-1.3.6.xml

ob-specberlin
ob-api-typepsd2

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.

For one-off access, this attribute has to be set to '1'. The frequency has to be greater than or equal to 1.

Use the below instructions to configure the FrequencyPerDay throttling policy:

  1. Open <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml.

    1. Change the attributes under the  apim.throttling tag as follows:

      [apim.throttling]
enable_data_publishing = true
jms.topic_connection_factory = "amqp://admin!wso2.com!carbon.super:$ref{super_admin.password}@clientid/carbon?brokerlist='tcp://${carbon.local.ip}:${jms.port}'"
receiver_username = "$ref{super_admin.username}@carbon.super"

    2. Make sure that the FrequencyPerDay property is enabled as follows:

      [open_banking.berlin.freq_per_day]
enable = true

  2. 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"/>

  3. 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. See here for the instructions. 

    In step 3, use $customProperty.accountId:$customProperty.consentId:$userId:$appId as the key template.

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 to share the same scope. 

  1. Sign in to the WSO2 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, remove an enumeration from an existing set and check whether the incoming request contains the defined enumerations. 

When an API is published, the swagger file is added as a local entry and saved under the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/local-entries directory.

To add the swagger as a local entry, the created and published API lifecycles are extended using customised API executor named com.wso2.finance.open.banking.api.executor.OBAPIPublisherExecutor. For more information on executors, see Extension Points of API Life cycle.  

When you modify the 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:

 Click here to see how to republish an API

  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. Enter a version number and click Create.

  4. You are redirected to the API Overview page.

  5. Go to API Definition using the left menu panel.
  6. Click EDIT.
  7. Modify the Swagger definition according to your requirements.
  8. Click UPDATE CONTENT.

  9. In the confirmation message box, click SAVE.