API Fundamentals

Developing an application that leverages the Encompass Lending Platform is straightforward. In this tutorial, we'll cover the fundamentals including authentication, loan retrieval and JSON/object mapping.

User Authentication

The first step is to authenticate the user and obtain an access token. If you're building a web application, the authorization code flow is the obvious choice; whereas, for console applications, the resource owner password credentials (ROPC) flow is generally the best option. (For more information about OAuth2, please refer to Authentication).

//set content and accept type
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON));

//prepare ROPC request
MultiValueMap<String, String> params = new LinkedMultiValueMap();
params.add("client_id", clientId);
params.add("client_secret", clientSecret);
params.add("grant_type", "password");
params.add("username", username);
params.add("password", password);
params.add("scope", "lp");

RestTemplate template = new RestTemplate();
HttpEntity<MultiValueMap<String, String>> entity = new HttpEntity(params, headers);

//authenticate user and obtain access token 
String response = template
  	.exchange(loanAUrl, HttpMethod.POST, entity, String.class)
  	.getBody();

As shown in Figure 1, in the ROPC request, you must supply application and user credentials and scope (this will always be "lp", which stands for Lending Platform). The application credentials are available to super administrator in Developer Connect under Account, API Key. The username is your fully qualified Encompass user ID, in the format @encompass:.

Lines 19-21 are noteworthy because they illustrate how to use the Spring HTTP client (i.e. RestTemplate) to interact with an API.

Expanding upon this, to convert the JSON string to a plain-old Java object (POJO), you'll need to create a bean and specify that class as the return type in the exchange method (see Figure 2). Use the JsonProperty annotation to define the mapping between a JSON property and class variable. Case in point, the annotation on line 2 maps the access_token property to the accessToken variable.

public class Client implements Serializable {
  @JsonProperty("access_token")
  private String accessToken;

  public String getAccessToken() {
    return accessToken;
  }
}

...
  
//obtain access token and convert to POJO
Client response = template
  	.exchange(loanUrl, HttpMethod.POST, entity, Client.class)
  	.getBody();

Loan Retrieval

The next step is to fetch the loan. To do this, we'll follow the same pattern shown in Figure 2, namely, we'll use the RestTemplate to query an API and convert the JSON response into a POJO.

public class Loan implements Serializable {
  @JsonProperty("encompassId")
  private String id;
  @JsonProperty("applications")
  private Application[] applications;
  ...
  
  public String getId() {
    return id;
  }
  
  public Application[] getApplications() {
    return applications;
  }

  ...
}

public class Application implements Serializable {
  @JsonProperty("id")
  private String id;
  @JsonProperty("assets")
  private Asset[] assets;
  ...
  
  public String getId() {
    return id;
  }

  public Asset[] getAssets() {
    return assets;
  }
  
  ...
}

public class Asset implements Serializable {
  @JsonProperty("id")
  private String id;
  @JsonProperty("assetType")
  private String assetType;
  @JsonProperty("borrowerId")
  private String borrowerId;
  @JsonProperty("isEmpty")
  private boolean isEmpty;

  public String getId() {
    return id;
  }

  public String getAssetType() {
    return assetType;
  }

  public String getBorrowerId() {
    return borrowerId;
  }

  public boolean isEmpty() {
    return isEmpty;
  }
}

...

//set content type and inject access token into authorization header
HttpHeaders headers = new HttpHeaders();
headers.setAccept(Arrays.asList(MediaType.APPLICATION_JSON));
headers.set("Authorization", String.format("Bearer %s", accessToken));

RestTemplate template = new RestTemplate();
HttpEntity<String> entity = new HttpEntity(headers);

//retrieve loan and convert to POJO
Loan loan = template
  	.exchange(loanUrl, HttpMethod.GET, entity, Loan.class, loanId)
  	.getBody();

As shown in Figure 3, the loan file consists of nested objects, a loan contains applications, which, in turn, contain assets and so forth, but this is no problem for the Jackson parser. To authorize the API call, be sure to include the access token in the Authorization header using the Bearer authentication scheme.

Summary

In this tutorial, we demonstrated how to use Spring Boot and Jackson to obtain an access token and interact with a loan file. In the next post, we'll expand on these ideas and explore how to replicate loans using the pipeline and webhook APIs.

To view the source code, please check out our GitHub repository