Java SDK

The Yodlee Java SDK provides a simple and efficient way to invoke Yodlee API services. Integration is quicker using the SDK, freeing up more time for developing your business solution.

The SDK offers:

  • Client credential-based authentication
  • Creation of JWT authentication tokens
  • Creation of token using SAML XML
  • Efficient synchronous and asynchronous API calls
  • Validation of payload and parameters before API invocation.

You must use Java runtime version JRE 1.7.0_131-b31 or higher.  An earlier JDK 1.7 is not adequate.  You need at least the stated build, or Java 1.8 or later.  You can download the latest Java SE Development Kit software from http://www.oracle.com/technetwork/java/javase/downloads/.

Use the Maven Build System

If you are already familiar with the Maven build automation tool, please skip ahead to the section headed "Connect your app to the SDK using Maven".  Read on for the Maven basics.

What is Maven?

  • Maven is an open source project management tool in widespread use.  It can be used for building and managing any Java-based project.
  • You can easily add jars and other project dependencies with Maven.
  • Maven provides project information (license, log document, dependency list, unit test reports, etc.)
  • Refer to http://maven.apache.org/ for more details.

What is the POM?

  • POM stands for "Project Object Model". It is an XML representation of a Maven project held in a file named pom.xml.
  • The POM file contains all the properties, dependencies, and project information in one place.
  • The POM file defines the build architecture of a project - the libraries, test suites, and dependencies.

What Next?

Connect Your App to the SDK Using Maven

The Yodlee SDK is a  a library that your app depends on. Tell Maven about the dependency by adding some lines to your Maven project’s pom.xml file, within the dependencies tag.

First, check the current version number of the yodlee java SDK, shown as 1.0.22 below.  Visit https://mvnrepository.com, and search for "yodlee".  In the search results, click on the heading "Yodlee Java SDK" to go to that repo page.  Look for the highest version number in the column headed "Version".  It will be a string like 1.0.22, and (if higher) use that string in place of 1.0.22 in the XML below.

<dependency>
	<groupid>com.yodlee </groupid>
	<artifactid> yodlee-java-sdk </artifactid>
    <version>1.0.22</version>
</dependency>

Next, make sure your current working directory is the project folder containing the pom.xml file. Build your project by executing the following command at the command prompt:

// Run from the project directory 
mvn clean install

This action downloads necessary dependencies, builds and installs your SDK-using app in one step. See http://maven.apache.org/  for more about installation and more information.  When your app builds without errors, you can get started with Yodlee API v1.1.

Alternatives for Developer Authentication

There are three alternative ways for a developer to authenticate themselves with the Yodlee API servers:

  • Client Credential-based Authentication: If you registered a developer account after April 2 2020, follow the Client Credential-based Authentication.

OR

  • Authentication using a JSON Web Token (JWT):  If you registered a developer account on or before April 2 2020, follow the JWT-based Authentication.

OR

  • Authentication using Security Assertion Markup Language (SAML): If you don't have a Yodlee developer account, you are probably using SAML-based Authentication, and should follow that section.

 Stop skim-reading at this point. Look at the credentials you have been issued on the dashboard of your Yodlee developer account. Follow the steps in only one of the three sections ahead. Follow the steps in the section appropriate to the credentials you have been given.

Alternative 1: Client Credential-based Authentication

Only follow these steps if your developer account dashboard lists a "clientId" and "secret".  To make an API call (HTTP request) based on client credential-based authentication, the SDK will create the necessary access token from the basic data you provide in the ClientCredentialUserConfiguration object. The steps follow:

  1. Create a string or file that contains client credential (clientId and secret), and API details in JSON string format.
  2. Read the JSON string/file and use a mapper library to stuff the JSON values into the Java ClientCredentialUserConfiguration object.
  3. Use the ClientCredentialUserConfiguration object to create a ClientCredentialUserContext object.
  4. Use the ClientCredentialUserContext object to instantiate an API call object, then make the call on that object, and receive the response.

Step 1: Create the JSON String containing the client credentials and API details.

An example of the JSON object is given below. The names in CAPITALS represent fields where you must place your actual values. All the attributes must be set as indicated.

Code sample of a JSON object of key/value pairs:

{
   "basePath":"APIBASEPATH",
   "apiVersion":"1.1",
   "clientId":"CLIENTID",
   "secret":"CLIENTSECRET",
   "loginName":"USERLOGINNAME",
   "socketTimeout":10000,
   "readTimeout":10000,
   "writeTimeout":10000
}

Note:

  • The values for APIBASEPATH, CLIENTID, and CLIENTSECRET come from the dashboard page of your Yodlee developer account.
  • In the sandbox, the USERLOGINNAME is created for you (for convenience), and is a string like "sbMem5c758c82bb1d11".
  • The USERLOGINNAME is 3 to 150 characters in length and must not contain any spaces.
  • In Development and Production environments, you will assign and administer the unique id string for each of your users.
  • The three network timeout values are in milleseconds, and are set to 10 seconds. Do not change these unless you are a TCP/IP network expert.

Step 2: Read the JSON string/file and use a mapper library to load the JSON values into a Java ClientCredentialUserConfiguration object.

The ClientCredentialUserConfiguration object will be used to create a User Access Token, specifying which end user's data you are working with. If a new (not previously seen) user's login name is passed, then that new user will be implicitly registered for you. When working in the Sandbox environment, you will always be working with a user token.

A few administrative API calls don't involve an end-user. In this case, you will create an admin access token using your adminUserLoginName assigned to you by Yodlee and visible on the dashboard of your yodlee developer account. An example adminUserLoginName (previously called an "Issuer ID") looks like "3d2d9393-b3fa-4054-bb50-46e3aeccbcfe". You never have to use an admin token for calls made in the Sandbox environment. You can create an admin token using a ClientCredentialAdminConfiguration, which is similar to the user configuration, but uses your assigned login name, in place of a user login name.

You can use a third-party library mapper to load the JSON string into a Java object. The Jackson library is the standard JSON library for Java, and can be found at https://github.com/FasterXML/jackson. You can read more about the Jackson library mapper at https://www.baeldung.com/jackson-object-mapper-tutorial. This JSON library will be another Maven dependency for your project. If you have a choice, use Jackson version 2.x and not the version 1.x.

// Use exception handlers as necessary 
ObjectMapper mapper = new ObjectMapper(); //Using Jackson library mapper

// Replace the placeholder "json-config" with the string of JSON data for your configuration.
ClientCredentialUserConfiguration clientCredentialUserConfiguration = mapper.readValue( "json-config", ClientCredentialUserConfiguration.class);


Step 3: Use the ClientCredential*Configuration object to create a ClientCredential*Context object.

In programming terms, a Context is the larger surrounding part that influences the behavior of the current unit of work. The SDK needs a little information about your runtime context, and this is provided through you creating and using a context object. The two types of context object follow:

  • ClientCredentialUserContext object: You will always work with a user token in the Sandbox environment. To create a user access token, load the values from the ClientCredentialUserContext object.
  • ClientCredentialAdminContext object: To create an admin access token, load the values from the ClientCredentialAdminContext object. An admin access token is used in one of the rare API calls that doesn't work with user data.

The ClientCredential*Context object can be created in a couple of lines of code, using a ContextBuilderFactory and your configuration object.

ClientCredentialAdminContextBuilder clientCredentialContextBuilder = ContextBuilderFactory.createClientCredentialAdminContextBuilder();

ClientCredentialAdminContext clientCredentialContext = clientCredentialContextBuilder.build(clientCredentialConfiguration);


Step 4: Use the ClientCredential*Context object to instantiate an API object, make the specific call on the API object, and receive the response.

//Invoking Get All Providers API (refer to API reference page) 
ProvidersApi providersApi = new ProvidersApi(clientCredentialContext); // Create API object
ApiResponse<ProviderResponse> providers  = providersApi.getAllProviders(capability, datasetFilter, name, priority, skip, top ); // Make API call
ProviderResponse providerResponse = providers.getData();  // Get response

The ClientCredentialAdminContext or ClientCredentialUserContext objects can be reused to invoke other APIs and can be accessed with an admin access token or user access token respectively.
Here's another example to invoke Get Accounts API using user access token context:

ClientCredentialUserContextBuilder clientCredentialUserContextBuilder = ContextBuilderFactory.createClientCredentialUserContextBuilder();
ObjectMapper mapper = new ObjectMapper(); 
//Replace the placeholder "json-config" with the input source for configuration. ClientCredentialUserConfiguration clientCredentialConfiguration = mapper.readValue("json-config", ClientCredentialUserConfiguration.class);
ClientCredentialUserContext clientCredentialUserContext = clientCredentialUserContextBuilder.build(clientCredentialConfiguration);
AccountsApi accountsApi = new AccountsApi(clientCredentialUserContext);
ApiResponse <accountresponse> accounts = accountsApi.getAllAccounts(accountId, container, include, providerAccountId, requestId, status);
AccountResponse accountResponse = accounts.getData();

The user context object can be reused to invoke other APIs and can be accessed with a user access token. Tokens expire no more than 30 minutes from their creation time.

Alternative 2: JWT-based Authentication

Only follow these steps if your developer account dashboard lists a "private key". 

Every API call (HTTP request) that you make to the Yodlee server must include a valid JSON Web Token (JWT). The SDK will create the necessary JWT from the basic data you provide in a JWT configuration object. The steps follow:

  1. Create a string or file that contains the token and API details in JSON string format.
  2. Read the JSON string/file and use a mapper library to stuff the JSON values into a Java JWT*Configuration object.
  3. Use the JWT*Configuration object to create a JWT*Context object.
  4. Use the JWT*Context object to instantiate an API call object, then make the call on that object, and receive the response.

Step 1: Create the JSON string containing the token and API details.

An example JSON object is given below.  The names enclosed in chevrons represent fields where you must place your actual values.  All the attributes must be set as applicable.  The "sub" field is only used when creating a user JWT. 

Code sample of A JSON object of key/value pairs:

{
	"basePath": "<api_base_path>",//API base path
	"apiVersion": "1.1",
	"apiKey": "<api_key>", //Issuer Id
	"privateKey": "<private_key>", //The private key needed to generate JWT Token
	"expiresIn": "<expires_in>", //lifetime for JWT token in secs, defaults to 1800
	"locale": "<locale>",
	"sub": "<sub>", //User Name.  Applicable only for JWTUserConfiguration
	"socketTimeout": 10000, // In millisecs, defaults to 10000
	"readTimeout": 10000,   // In millisecs, defaults to 10000
	"writeTimeout": 10000   // In millisecs, defaults to 10000	
}


Step 2: Read the JSON string/file and use a mapper library to load the JSON values into a Java JWT*Configuration object.

There are two types of JWT*Configuration objects.  If you are creating an app token, then load the values into a JWTAppConfiguration object.  If you are creating a user token, then load the values into a JWTUserConfiguration object. You can use a third-party library mapper to load the JSON string into a Java object.  The Jackson library is the standard JSON library for Java, and can be found at https://github.com/FasterXML/jackson. You can read more about the Jackson library mapper at https://www.baeldung.com/jackson-object-mapper-tutorial.  This JSON library will be another Maven dependency for your project. Use Jackson version 2.x, not 1.x, if you have a choice.

// Use exception handlers as necessary 
ObjectMapper mapper = new ObjectMapper(); //Using Jackson library mapper

// Replace the placeholder <json-config> with the data for your configuration.
JWTAppConfiguration jwtConfiguration 
        = mapper.readValue( "<json-config>", JWTAppConfiguration.class);


Step 3: Use the JWT*Configuration object to create a JWT*Context object.

In programming terms, a Context is the larger surrounding part that influences the behavior of the current unit of work. The SDK needs a little information about your runtime context, and this is provided through you creating and using a Context object. There are two kinds of Context objects here.  If you are creating an app token, then load the values into a JWTAppContext object.  If you are creating a user token, then load the values into a JWTUserContext object.  The JWT*Context object can be created in a couple of lines of code, using a ContextBuilderFactory and your configuration object.

JWTAppContextBuilder jwtAppContextBuilder =
        ContextBuilderFactory.createJWTAppContextBuilder();

JWTAppContext jwtAppContext = jwtAppContextBuilder.build(jwtConfiguration);


Step 4: Use the JWT*Context object to instantiate an API object, make the specific call on the API object, and receive the response.

//Invoking Get All Providers API (refer to API reference page) 
ProvidersApi providersApi = new ProvidersApi(jwtAppContext); // Create API object

ApiResponse<providerresponse> providers    // Make API call
        = providersApi.getAllProviders(capability, datasetFilter, 
                                       name, priority, skip, top ); 

ProviderResponse providerResponse = providers.getData();  // Get response

The JWTAppContext object can be reused to invoke other APIs which can be accessed with an app token.

Here's another example to invoke Get Accounts API using a JWT User token context:

JWTUserContextBuilder jwtUserContextBuilder = 
                         ContextBuilderFactory.createJWTUserContextBuilder();

ObjectMapper mapper = new ObjectMapper(); 

//Replace the placeholder <json-config> with the input source for configuration. 
JWTUserConfiguration jwtConfiguration 
       = mapper.readValue("<json-config>", JWTUserConfiguration.class);

JWTUserContext jwtUserContext = jwtUserContextBuilder.build(jwtConfiguration);

AccountsApi accountsApi = new AccountsApi(jwtUserContext);
			
ApiResponse<accountresponse> accounts 
       = accountsApi.getAllAccounts(accountId, container, include, 
                                    providerAccountId, requestId, status);
 
AccountResponse accountResponse = accounts.getData();

The JWT user context object can be reused to invoke other APIs which can be accessed with a user token. Tokens expire no more than 30 minutes from their creation time. 

Alternative 3: SAML-based Authentication

The SDK will create the authentication credential from the basic data you provide in a configuration object. The steps follow:

  1. Create a string or file that contains your data and some API details, in JSON string format.
  2. Read the JSON string/file and use a mapper library to load the JSON values into a Java configuration object.
  3. Use the Configuration object to create a Context objec.t
  4. Use the Context object to instantiate an API object, make the specific call on the API object, and receive the response.

Step 1: Create the JSON string containing your developer details and some API details.

An example JSON object is given below.  The names enclosed in chevrons represent fields where you must place your actual values. All the attributes must be set as applicable. 

{
	"basePath": "<api_base_path>",//API base path for v1.1 APIs
	"apiVersion": "1.1",
	"cobrandName": "<cobrand_name>", //The cobrand name
	"issuer": "<issuer>",//The issuer
	"source": "<source>",//The source
	"samlResponse": "<saml_response>",//SAML response XML
	"socketTimeout": 10000, // In millisecs, defaults to 10000
	"readTimeout": 10000,   // In millisecs, defaults to 10000
	"writeTimeout": 10000   // In millisecs, defaults to 10000
}


Step 2: Read the JSON string/file and use a mapper library to load the JSON values into a Java Configuration object.

There are two types of Configuration objects. If you are invoking a cobrand session-based API call, then load the values into a CobrandConfiguration object. If you are invoking a user session-based API call (i.e. a call to work with the data of a specific existing user) then load the values into a UserConfiguration object. You can use a third-party library mapper to load the JSON string into a Java object.  The Jackson library is the standard JSON library for Java, and can be found at https://github.com/FasterXML/jackson You can read more about the Jackson library mapper at https://www.baeldung.com/jackson-object-mapper-tutorial.  This JSON library will be another Maven dependency for your project. If you have a choice, use Jackson version 2.x and not version 1.x.

// Use appropriate exception handlers 
ObjectMapper mapper = new ObjectMapper(); //Using Jackson library mapper 

// Replace placeholder <json-config> with the input source for configuration
CobrandConfiguration configuration 
        = mapper.readValue("<json-config>", CobrandConfiguration.class); 


Step 3: Use the Configuration object to create a Context object.

In programming terms, a Context is the larger surrounding part that influences the behavior of your current unit of work. The SDK needs a little information about your runtime context, and this is provided through you creating and using a Context object.

There are two kinds of Context objects here. If you are invoking a cobrand session-based API call, then create a CobrandContext object.  If you are invoking a user session-based API call (i.e. a call to work with the data of a specific existing user) then create a UserContext object.  The Context object can be created in a couple of lines of code, using a ContextBuilderFactory and your configuration object.

CobrandContextBuilder cobrandContextBuilder
        = ContextBuilderFactory.createCobrandContextBuilder();

CobrandContext cobrandContext  
        = CobrandContextBuilder.build(configuration);


Step 4: Use the Context object to instantiate an API object, make the specific call on the API object, and receive the response.

//Invoking Get All Providers API (refer to API reference page) 
ProvidersApi providersApi = new ProvidersApi(cobrandContext); // Create API object

ApiResponse<providerresponse> providers    // Make API call
        = providersApi.getAllProviders(capability, datasetFilter, 
                                       name, priority, skip, top ); 

ProviderResponse providerResponse = providers.getData();  // Get response

The Cobrand context object can be reused to invoke other cobrand context-based APIs. The idle timeout for a cobrand context is 2 hours and the absolute timeout is 24 hours. 

Here's an example of a User Context-based API call:

// Add exception handlers as needed
ObjectMapper mapper = new ObjectMapper(); // Using Jackson library mapper

//Replace placeholder <json-config> with the input source for configuration
UserConfiguration userConfiguration 
        = mapper.readValue("<json-config>", UserConfiguration.class);

UserContextBuilder userContextBuilder 
        = ContextBuilderFactory.createUserContextBuilder();
UserContext userContext = userContextBuilder.build(userConfiguration);
AccountsApi accountsApi = new AccountsApi(userContext);
			
ApiResponse<accountresponse> accounts =
					accountsApi.getAllAccounts(accountId, container, include, providerAccountId, requestId, status);
AccountResponse accountResponse = accounts.getData();

The highlighted User context object can be reused to invoke other users context-based APIs. The idle timeout for a user context is 30 minutes and the absolute timeout is 2 hours. This concludes the section on authenticating using SAML.

Validation and Exception Structure

When an API is invoked, the SDK performs model and request parameter validation to find any problems with the request. In the case of one or more problems being identified, the code throws an API exception with all the issues listed as problem objects.

A printable representation of an ApiException looks like the example below: 

ApiException[
    problems=[
        Problem [
            errorCode=Y800,
            constraintViolation=Invalid value for accountId,
            propertyPath=
        ]
    ]
    isClientSideError=true,
    responseHeaders={},
    responseBody=null,
    message=Validation failed.
]

Overloaded Endpoint Names

There are endpoints that are capable of fulfilling multiple objectives. The SDK supplies dedicated methods for each function:

This table demonstrates the mapping of endpoints and method names.

Endpoint Method Names
Post /verification
  • initiateCDVerification
  • performMatchingVerification

Changing HTTP Timeouts

The HTTP client network timeouts can be configured by setting these attributes in a configuration object:

  • socketTimeout - sets the value for socket timeout
  • readTimeout - sets the value for read timeout
  • writeTimeout – sets the value for write timeout

If the above attributes are not set in the configuration object then default values of HTTP client are taken which is 10 seconds for all the attributes.

We recommend not changing these attributes without a very good reason.

Making Asynchronous API Calls

The basic way to make API calls with the SDK is through the use of synchronous methods provided in each API entity wherein the invoker thread waits till the API call returns. Using asynchronous method looks something like this:

AccountsApi accountsApi = new AccountsApi(userContext);
ApiResponse<accountresponse> accounts 
        = accountsApi.getAllAccounts(accountId, container, include,
                                     providerAccountId, requestId, status); 

However, if you need to perform these calls in the background i.e., you do not want the invoker thread to wait for the API response, there is an asynchronous method corresponding to each synchronous method.

All the asynchronous methods accept a callback object and follow a naming convention: the name of the synchronous method with the suffix ‘Async’. For example, the asynchronous method of the above API call looks like this:

 final CountDownLatch latch = new CountDownLatch(1);
AccountsApi accountsApi = new AccountsApi(userContext);

accountsApi.getAllAccountsAsync(accountId, container, include, 
                                providerAccountId, requestId, status,
    new ApiCallbackAdapter<accountresponse>() {
       @Override
	       public void onSuccess(AccountResponse result, int statusCode,
					Map<string, list=<String>> responseHeaders) {
			super.onSuccess(result, statusCode, responseHeaders);
			System.out.println("Status Code: "+statusCode);
			latch.countDown();
		}
	});
latch.await(); 

In the above example, CountDownLatch is a synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes. Refer to Oracle Java docs for more information on CountDownLatch. Here it is used for demo purposes only, and you may not need or use it.