Getting started

How to Build

The generated SDK relies on Node Package Manager (NPM) being available to resolve dependencies. If you don't already have NPM installed, please go ahead and follow instructions to install NPM from here. The SDK also requires Node to be installed. If Node isn't already installed, please install it from here

NPM is installed by default when Node is installed

To check if node and npm have been successfully installed, write the following commands in command prompt:

• node --version
• npm -version

Now use npm to resolve all dependencies by running the following command in the root directory (of the SDK folder):

npm install

This will install all dependencies in the node_modules folder.

Once dependencies are resolved, you will need to move the folder Bnzapimatic in to your node_modules folder.

How to Use

The following section explains how to use the library in a new project.

1. Open Project Folder

Open an IDE/Text Editor for JavaScript like Sublime Text. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Click on File and select Open Folder.

Select the folder of your SDK and click on Select Folder to open it up in Sublime Text. The folder will become visible in the bar on the left.

2. Creating a Test File

Now right click on the folder name and select the New File option to create a new test file. Save it as index.js Now import the generated NodeJS library using the following lines of code:

var lib = require('lib');

Save changes.

3. Running The Test File

To run the index.js file, open up the command prompt and navigate to the Path where the SDK folder resides. Type the following command to run the file:

node index.js

How to Test

These tests use Mocha framework for testing, coupled with Chai for assertions. These dependencies need to be installed for tests to run. Tests can be run in a number of ways:

Method 1 (Run all tests)

1. Navigate to the root directory of the SDK folder from command prompt.
2. Type mocha --recursive to run all the tests.

Method 2 (Run all tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha * to run all the tests.

Method 3 (Run specific controller's tests)

1. Navigate to the ../test/Controllers/ directory from command prompt.
2. Type mocha APIMatic Ltd Bank Feeds SandboxController to run all the tests in that controller file.

To increase mocha's default timeout, you can change the TEST_TIMEOUT parameter's value in TestBootstrap.js.

Initialization

Authentication

In order to setup authentication in the API client, you need the following information.

| Parameter | Description | |-----------|-------------| | oAuthClientId | OAuth 2 Client ID | | oAuthClientSecret | OAuth 2 Client Secret | | oAuthRedirectUri | OAuth 2 Redirection endpoint or Callback Uri |

API client can be initialized as following:

const lib = require('lib');

// Configuration parameters and credentials
lib.Configuration.oAuthClientId = "oAuthClientId"; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = "oAuthClientSecret"; // OAuth 2 Client Secret
lib.Configuration.oAuthRedirectUri = "oAuthRedirectUri"; // OAuth 2 Redirection endpoint or Callback Uri

You must now authorize the client.

Authorizing your client

Your application must obtain user authorization before it can execute an endpoint call. The SDK uses OAuth 2.0 authorization to obtain a user's consent to perform an API request on user's behalf.

1. Obtaining user consent

To obtain user's consent, you must redirect the user to the authorization page. The buildAuthorizationUrl() method creates the URL to the authorization page. You must pass the scopes for which you need permission to access.

const oAuthManager = lib.OAuthManager;
const authUrl = oAuthManager.buildAuthorizationUrl([lib.OAuthScopeEnum.BANKFEEDS]);
// open up the authUrl in the browser

2. Handle the OAuth server response

Once the user responds to the consent request, the OAuth 2.0 server responds to your application's access request by using the URL specified in the request.

If the user approves the request, the authorization code will be sent as the code query string:

https://example.com/oauth/callback?code=XXXXXXXXXXXXXXXXXXXXXXXXX

If the user does not approve the request, the response contains an error query string:

https://example.com/oauth/callback?error=access_denied

3. Authorize the client using the code

After the server receives the code, it can exchange this for an access token. The access token is an object containing information for authorizing the client and refreshing the token itself.

const tokenPromise = oAuthManager.authorize(code);

The Node.js SDK supports both callbacks and promises. So, the authorize call returns a promise and also returns response back in the callback (if one is provided)

Scopes

Scopes enable your application to only request access to the resources it needs while enabling users to control the amount of access they grant to your application. Available scopes are defined in the lib/Models/OAuthScopeEnum enumeration.

| Scope Name | Description | | --- | --- | | BANKFEEDS | |

Refreshing token

Access tokens may expire after sometime. To extend its lifetime, you must refresh the token.

const refreshPromise = oAuthManager.refreshToken();
refreshPromise.then(() => {
    // token has been refreshed
} , (exception) => {
    // error occurred, exception will be of type lib/Exceptions/OAuthProviderException
});

If a token expires, the SDK will attempt to automatically refresh the token before the next endpoint call which requires authentication.

Storing an access token for reuse

It is recommended that you store the access token for reuse.

This code snippet stores the access token in a session for an express application. It uses the cookie-parser and cookie-session npm packages for storing the access token.

const express = require('express');
const cookieParser = require('cookie-parser');
const cookieSession = require('cookie-session');

const app = express();
app.use(cookieParser());
app.use(cookieSession({
  name: 'session',
  keys: ['key1']
}));

const lib = require('lib');
...
// store token in the session
req.session.token = lib.Configuration.oAuthToken;

However, since the the SDK will attempt to automatically refresh the token when it expires, it is recommended that you register a token update callback to detect any change to the access token.

lib.Configuration.oAuthTokenUpdateCallback = function(token) {
    // getting the updated token
    req.session.token = token;
}

The token update callback will be fired upon authorization as well as token refresh.

Creating a client from a stored token

To authorize a client from a stored access token, just set the access token in Configuration along with the other configuration parameters before making endpoint calls:

const express = require('express');
const cookieParser = require('cookie-parser');
const cookieSession = require('cookie-session');

const app = express();
app.use(cookieParser());
app.use(cookieSession({
  name: 'session',
  keys: ['key1']
}));

const lib = require('lib');

app.get('/', (req, res) => {
    lib.Configuration.oAuthToken = req.session.token; // the access token stored in the session
});

Complete example

This example demonstrates an express application (which uses cookie-parser and cookie-session) for handling session persistence.

In this example, there are 2 endpoints. The base endpoint '/' first checks if the token is stored in the session. If it is, sdk endpoints can be called.

However, if the token is not set in the session, then authorization url is built and opened up. The response comes back at the '/callback' endpoint, which uses the code to authorize the client and store the token in the session. It then redirects back to the base endpoint for calling endpoints from the SDK.

app.js

const express = require('express');
const app = express();
const cookieParser = require('cookie-parser');
const cookieSession = require('cookie-session');

app.use(cookieParser());
app.use(cookieSession({
  name: 'session',
  keys: ['key1']
}));
const PORT = 1800;

const lib = require('lib');
const oAuthManager = lib.OAuthManager;
lib.Configuration.oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
lib.Configuration.oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret
lib.Configuration.oAuthRedirectUri = 'http://localhost:1800/callback'; // OAuth 2 Redirection endpoint or Callback Uri


app.listen(PORT, () => {
    console.log('Listening on port ' + PORT);
});

app.get('/', (req, res) => {
    if (req.session.token !== null &&
          req.session.token !== undefined) {
        // token is already set in the session
        // now make API calls as required
        // client will automatically refresh the token when it expires and call the token update callback
    } else {
        const scopes = [lib.OAuthScopeEnum.BANKFEEDS];
        const authUrl = oAuthManager.buildAuthorizationUrl(scopes);
        res.redirect(authUrl);
    }
});

app.get('/callback', (req, res) => {
    const authCode = req.query.code;

    const promise = oAuthManager.authorize(authCode);
    promise.then((success) => {
        req.session.token = lib.Configuration.oAuthToken;
        res.redirect('/');
    }, (exception) => {
        // error occurred, exception will be of type lib/Exceptions/OAuthProviderException
    });
});

Class Reference

List of Controllers

• MiscController

MiscController

Get singleton instance

The singleton instance of the MiscController class can be accessed from the API Client.

var controller = lib.MiscController;

gETauthorizationcode

GET authorization code

function gETauthorizationcode(responseType, clientId, redirectUri, scope, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | responseType | Required | TODO: Add a parameter description | | clientId | Required | TODO: Add a parameter description | | redirectUri | Required | TODO: Add a parameter description | | scope | Required | TODO: Add a parameter description |

Example Usage

    var responseType = code;
    var clientId = 1U5hCE3h3AhCJXGNgOstGp6drkaMxB4S;
    var redirectUri = https://www.apimatic.io/;
    var scope = 'bankfeeds';

    controller.gETauthorizationcode(responseType, clientId, redirectUri, scope, function(error, response, context) {

    
    });

getaccesstoken

Get access token

function getaccesstoken(grantType, redirectUri, code, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | grantType | Required | TODO: Add a parameter description | | redirectUri | Required | TODO: Add a parameter description | | code | Required | TODO: Add a parameter description |

Example Usage

    var grantType = authorization_code;
    var redirectUri = https://www.apimatic.io/;
    var code = 'g4q7Bsr8bJ7YMYfVHc9Ceq475d17JZsXhMYAABkh';

    controller.getaccesstoken(grantType, redirectUri, code, function(error, response, context) {

    
    });

gETv3Accounts

GET v3/accounts

function gETv3Accounts(apikey, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | apikey | Required | TODO: Add a parameter description |

Example Usage

    var apikey = 'VD9ww2IxRnUWtTUYipeDx33GUTYHJRpn';

    controller.gETv3Accounts(apikey, function(error, response, context) {

    
    });

gETv2Transactions

GET v2/transactions

function gETv2Transactions(accountId, from, to, limit, apikey, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | accountId | Required | TODO: Add a parameter description | | from | Required | TODO: Add a parameter description | | to | Required | TODO: Add a parameter description | | limit | Required | TODO: Add a parameter description | | apikey | Required | TODO: Add a parameter description |

Example Usage

    var accountId = 'eyJjb2RlIjoiQyIsImlkIjoiMDAwMDI0MzIxMDAwMjQ3ODAwMCJ9';
    var from = '2018-09-01';
    var to = '2021-04-16';
    var limit = 1000;
    var apikey = 'VD9ww2IxRnUWtTUYipeDx33GUTYHJRpn';

    controller.gETv2Transactions(accountId, from, to, limit, apikey, function(error, response, context) {

    
    });

revokerefreshtoken

Revoke refresh token

function revokerefreshtoken(token, tokenTypeHint, callback)

Parameters

| Parameter | Tags | Description | |-----------|------|-------------| | token | Required | TODO: Add a parameter description | | tokenTypeHint | Required | TODO: Add a parameter description |

Example Usage

    var token = 'token';
    var tokenTypeHint = token_type_hint;

    controller.revokerefreshtoken(token, tokenTypeHint, function(error, response, context) {

    
    });

Back to List of Controllers