Generating Clients Using Swagger

Generate a client using the Yodlee OpenAPI Specification and Swagger available on GitHub.

Introduction

Here, we explain how to use the Yodlee OpenAPI specification file to generate a client-side library interface (SDK) in the programming language of your choice. Follow the steps below to generate an SDK for the Java language. About 30 other programming languages and platforms are supported.

Steps to Generate a Java Client Using an Online Tool

Typically, you now add the generated client library to your IDE and make it known to your build system. Details vary for different IDEs and build systems, and the developer is assumed to know the steps for the tools they use.

The generated client is ready for Maven and Gradle-based build systems. It also generates a Travis CI integration file (for continuous integration at GitHub).

Download the YAML file to a convenient location on your system.
Access https://editor.swagger.io/ in your browser.
In the swagger.io editor, import the YAML file from your system or paste the file contents into the online editor using the menu option.
Visit the Generate Client menu and select your preferred language.
Your generated SDK client files (java-client-generated.zip) are downloaded.
On extracting the java-client-generated.zip file, you can see the generated files and folders.
You can see the following generated structure in your IDE (this screenshot was taken in the Eclipse IDE).

Steps to Generate a Java Client Offline

Here, we will explain how we can generate client code without accessing https://editor.swagger.io/. We do this by using the Swagger Codegen JAR file.

Download the YAML to a convenient location on your system.
Download the required JAR file swagger-codegen-cli-.jar from Maven Central or visit this site.
For the purpose of demonstration, we will use the file swagger-codegen-cli-2.4.4.jar.
Go to the location of the JAR file in the command line and give the following command to generate the client.

java -jar swagger-codegen-cli-2.4.4.jar generate -i swagger.yaml --
group-id com.yodlee --artifact-id com.yodlee.api.swagger.client --
artifact-version 1.0.0-SNAPSHOT -l java --library resttemplate -o spring-swagger-codegen-api-client

The argument list contains:
1. -i :
  The location and name of the input YAML file. (In our case it is swagger.yaml)
2. --group-id, --artifact-id, --artifact-version:
  Maven project properties for the generated project.
3. -l java:
  The language of the generated client.
4. --library:
  Generate the JAVA client for the following frameworks:
  - resttemplate - Spring RestTemplate + Jackson
  - jersey1 - Jersey1 + Jackson
  - jersey2 - Jersey2 + Jackson
  - feign - OpenFeign + Jackson
  - okhttp-gson - OkHttp + Gson
  - retrofit (Obsolete) - Retrofit1/OkHttp + Gson
  - retrofit2 - Retrofit2/OkHttp + Gson
  - rest-easy - Resteasy + Jackson
5. -o:
  The location and name of the output directory where the client will be generated. The extracted directory contents as described in the on-line section will be seen in this output directory.

Note: For a list of available languages you can visit https://editor.swagger.io/. Alternatively, you can run the following command:

java -jar swagger-codegen-cli-2.4.4.jar

Setting the API Base Path and HTTP Headers

Before making any API call, set the ApiClient with the base path and some common HTTP Headers.

Step 1: Setting the API Base Path

Set the server base URL in the base path of the API client object.

Sample Code Snippet:

AccountsApi accountApi = new AccountsApi();
ApiClient defaultApiClient = accountApi.getApiClient();
defaultApiClient.setBasePath("<server_base_url>");</server_base_url>

Step 2: Setting Common HTTP Headers

Set the following HTTP header values in the corresponding API client object under the io.swagger.client.api package before making any API call.

Sample Code Snippet:

defaultApiClient.addDefaultHeader("Content-Type", "application/json");
defaultApiClient.addDefaultHeader("Api-Version", "1.1");
defaultApiClient.addDefaultHeader("Cobrand-Name", "<cobrand_name>");</cobrand_name>

Note: We recommend that you create an instance of the ApiClient for each thread in a multithreaded environment to avoid any potential issues.

Invoking APIs Using Swagger SDK

Yodlee APIs v1.1 supports the following authentication mechanisms:

Client Credential-based Authentication
API Key-based Authentication
SAML-based Authentication

Client Credential-based Authentication

Step 1: Obtain the Access Token
Obtain the access token by sending clientId, secret, and loginName issued during developer registration or an existing user in the form-url-encoded request. If a non-existing username is passed in loginName, then the user will be implicitly registered.
Set the ApiClient with the access token in the Authorization header obtained from the form-url-encoded request.

//Instantiate an ApiClient and set the API base path to fetch the access token
    ApiClient apiClient = new ApiClient();
    apiClient.setBasePath("<api_base_path>");

    // Add Headers
    Map<string, string=""> headers = new HashMap&lt;&gt;();
    headers.put("Api-Version","1.1");
    headers.put("Content-Type", "application/x-www-form-urlencoded");
    //LOGIN_NAME could be *_ADMIN obtained during developer registration
    //OR any existing user or any user you would want to register 
    headers.put("loginName", "<login_name>");

    // Add Form Parameters
    Map<string, object=""> formParams = new HashMap&lt;&gt;();
    formParams.put("clientId", "<client_id>");
    formParams.put("secret", "<secret>");

    //Build Call object
    Call call = apiClient.buildCall("/auth/token", "POST", Collections.emptyList(), Collections.emptyList(), null, headers, formParams, Collections.emptyList().toArray(new String[0]), null);

    //Invoke API to obtain the access token response
    ApiResponse<clientcredentialtokenresponse> clientCredentialTokenResponse = apiClient.execute(call, ClientCredentialTokenResponse.class);
    ClientCredentialTokenResponse response = clientCredentialTokenResponse.getData();
    ClientCredentialToken token = response.getToken();
    // Set the Header Authorization Bearer token in Default ApiClient
    ApiClient apiClient = new ApiClient();
    apiClient.addDefaultHeader("Authorization", "Bearer " + token.getAccessToken());
    apiClient.addDefaultHeader("Api-Version","1.1");
    apiClient.addDefaultHeader("Content-Type", "application/json");

    //Updates system to use this ApiClient as default
    Configuration.setDefaultApiClient(apiClient);
    </clientcredentialtokenresponse></secret></client_id></string,></login_name></string,></api_base_path>

Step 2: API Invocation
Create an instance of the API object, set the input parameters, and invoke the respective method.

Sample Code Snippet:

AccountsApi apiInstance = new AccountsApi();
    Long accountId = 789L; // Long | accountId
    String container = "bank"; // String eg.
    String include = "profile"; // String eg.
    try {
        ApiResponse<accountresponse> result = apiInstance.getAccountWithHttpInfo(accountId, container, include);
        if(result.getStatusCode() == 200){
        AccountResponse accountModel = result.getData();
          System.out.println("Success");
        }
    } catch (ApiException e) {
        System.err.println("Exception when calling AccountApi#getAccount");
        e.printStackTrace();
    }</accountresponse>

API Key-based Authentication

Step 1: Setting Authorization HTTP Header
You will have to set the header before making the API call.

defaultApiClient.addDefaultHeader("Authorization", "Bearer <jwt-token>");</jwt-token>

Step 2: API Invocation
Create an instance of the API object, set the input parameters, and invoke the respective method.

Sample Code Snippet:

AccountsApi apiInstance = new AccountsApi();
Long accountId = 789L; // Long | accountId
String container = "bank"; // String eg.
String include = "profile"; // String eg.
try {
    ApiResponse<accountresponse> result = apiInstance.getAccountWithHttpInfo(accountId, container, include);
    if(result.getStatusCode() == 200){
	AccountResponse accountModel = result.getData();
      System.out.println("Success");
    }
} catch (ApiException e) {
    System.err.println("Exception when calling AccountApi#getAccount");
    e.printStackTrace();
}</accountresponse>

SAML-based Authentication

SAML Caution

SAML is an approach to authentication used by some large financial institutions. The use of SAML requires advance planning to configure a server environment. Unless your institution has standardized on SAML, please use API-key-based authentication. To know more about Yodlee Authentication, visit the Getting Started with Client Credentials page.

Step 1: Obtain cobSession
Invoke CobrandApi.cobrandLogin() to obtain cobSession

Sample Code Snippet:

CobrandApi cobrandApi = new CobrandApi();
ApiClient apiClient = cobrandApi.getApiClient();
CobrandLoginRequest cobrandLoginRequest = new CobrandLoginRequest();
Cobrand cobrand = new Cobrand();
cobrand.setCobrandLogin(<cobrandlogin-name>);
cobrand.setCobrandPassword(<cobrandpassword>);
cobrandLoginRequest.setCobrand(cobrand);
//Invoking the cobrand login API to fetch cobsession
ApiResponse<cobrandloginresponse> response = cobrandApi.cobrandLoginWithHttpInfo(cobrandLoginRequest);
if(response.getStatusCode() == 200){
  //Cobsession obtained
  String cobsession = response.getSession().getCobSession());
}</cobrandloginresponse></cobrandpassword></cobrandlogin-name>

Step 2: Setting cobSession in Authorization HTTP Header and Obtain userSession
Set the cobSession obtained in the previous step in the header and invoke the CobrandApi.samlLogin() to obtain the userSession

Sample Code Snippet:

UserApi userApi = new UserApi();

//Set the cobsession value in HTTP Header
StringBuilder builder = new StringBuilder();
ApiClient apiClient = userApi.getApiClient();
// Value format {cobSession={{cobrandToken}}}
builder.append("{cobSession=").append(cobsession).append("}");
apiClient.addDefaultHeader("Authorization", builder.toString());

//Invoke SAML Login API
String issuer = "<issuer>";
String source = "<source />";
String samlResponse = "<saml response="" xml="">";
ApiResponse<userresponse> userResponse = userApi.samlLoginWithHttpInfo (issuer, samlResponse, source);
if(userResponse.getStatusCode() == 200){
    String userSession = userResponse.getUser().getSession().getUserSession();
}</userresponse></saml></issuer>

Step 3: Setting cobSession and userSession in Authorization HTTP Header and API Invocation
Create an instance of the API object, set the input parameters, and invoke the respective method.

Sample Code Snippet:

AccountsApi accountApi = new AccountsApi();
ApiClient apiClient = accountApi.getApiClient();
// Building the Authorization key in the format shown in next line
// {cobSession={{cobrandToken}}, userSession={{userToken}}}
StringBuilder builder = new StringBuilder();
builder.append("{cobSession=").append(cobsession).append(",").append("userSession=").append(userSession).append("}");

// Setting HTTP Header Authorization key with the cobsession and userSession
apiClient.addDefaultHeader("Authorization", builder.toString());

// Setting the input parameters
String accountId = null;
String container = "creditCard";
String include = null;
String providerAccountId = null;
String requestId = null;
String status = null;

// Calling the API to get the AccountResponse that has all the accounts’ information
ApiResponse<accountresponse> accountResponse = accountApi.getAllAccountsWithHttpInfo(accountId, container, include, providerAccountId, requestId, status);

if(accountResponse.getStatusCode() == 200){
   AccountResponse accountModel = accountResponse.getData();
   System.out.println("Successfully fetched account model");
}</accountresponse>

API Exception

When an API call hits an exception, the details can be fetched from

//Assuming e is instance of ApiException
String responseBody = e.getResponseBody();

You can use YodleeError model object to de-serialize the above JSON message and review the error.

Appendix

If you have generated a Java Client, you may want to execute the following text replacement across the generated Java code to get better feedback on the Javadoc help generated by IDEs.
Please replace the below text across generated Java project –

< with <
> with >

With this text replacement, you can see Content Assist, which will be very helpful for rapid development.

This step needs to be carried out for a Java client because the Java code generator for Swagger applies an escape sequence on HTML tags within the Javadoc, which is a bug within it.