V1 vs V3 Encompass APIs, what’s the difference?

October 14, 2022 | Nikhil Modak

🚧

Please note > This information is specific to the Encompass APIs where the first segment of the API path includes “/Encompass”.

If you have found yourself trying to wrap your mind around the API versioning in Encompass Developer Connect, this blog post will be especially of interest to you.  

In this article we are addressing common questions that are raised with respect to API versioning in Encompass Developer Connect. What is the difference between V1 and V3 Loan APIs, and when and why should I use one or the other version?

So, what’s the difference?

The difference between V1 and V3 APIs can be summarized into 2 areas — technological and functional.

Technological

The Encompass V1 REST APIs are RESTFUL wrappers on our legacy SOAP/WCF APIs; hence the APIs broadly follow REST standards. For the end user of these APIs, V1 APIs work just like REST, however, our engineers need to write a lot more code to use the underlying SOAP API in a RESTful way. On the other hand, V3 APIs are true REST operations that follow industry guidelines and principles and come with all the added benefits of a RESTful call.

The transition from V1 to V3 was not simply changes in the contracts - it required a tech stack refresh, to create a much leaner codebase. Therefore, V1 and V3 APIs currently live in different codebases of Encompass, however, to simplify the experience from the API consumer point of view, our API gateway does all the heavy lifting to determine which codebase the API call needs to be routed to.

Functional

With V3 APIs, we were able to correct some of the low-level issues (i.e., related to the data store design) we had observed that we could not modify the V1 codebase without breaking client integrations.

For V3 APIs, we have tried to use industry standards such as loan JSON schema and JSON paths. With the V3 loan schema we can use third-party libraries or tools to parse it and create C# or Java contracts. That is not possible in the V1 loan schema.  

Why should I migrate to V3 APIs?

There are some more obvious benefits for using V3 REST APIs, such as improved performance (due to the leaner code base), error handling, messaging, and adherence to the principles and standards of the RESTful API design. In addition, there are other benefits of using V3 APIs especially as it pertains to managing collection entities in Encompass.

Segregation of Fixed vs Variable collection entities

When we look at the Encompass UI, certain entities such as Assets, Liabilities and Income can have fixed number of entries (pre-URLA), and others such as Verification of Deposits, Verification of Employments allow variable number of entries.

The V1 contracts combine some of these into a single contract. Let us consider Assets (Fixed-size collection) and Verification of Deposits or VODs (a variable-size collection) are combined into a single contract in V1 APIs. As a result, it puts the burden on the end user to determine the actual collection type they are dealing with and update the properties applicable to the respective collection (Asset or VOD). Furthermore, Assets entries (being a fixed size) are created when the loan is created, and the user is allowed to update those properties, but not allowed to create or delete assets. VODs, on the other hand, are variable in size and the user should be allowed to add, delete or reorder these. Combining these two in a single collection makes governance and usability extremely difficult.

The V3 contracts in contrast have a clear distinction between fixed and variable size collections. Any collections that were a mix of the two were separated into two or more collections each with their own contract and property settings.

Identification of collection entities

The V1 contracts do not enforce a strict standard on IDs. Some entities have unique IDs, and some have IDs based on the position of the entry in the collection. This makes identification, updates and reordering tricky.

The V3 contracts, on the other hand, have well defined standards including:

• Fixed-size collection entities will not have an Id property - because they are fixed in size and each entity has a specific purpose, they can be identified using values of one or more Metadata properties on the entity.
• Variable-size collection entities have a system generated unique id. This ID is guaranteed to be unique within the loan and does not change throughout the lifetime of the entity (creation to deletion).

When should I use V1 vs V3 APIs?

If you are just starting out with ICE Mortgage Technology APIs, the recommended best practice is to always use the V3 API when its available, if not, use V1.

If you are already using V1 APIs, the recommendation would be to migrate to V3 APIs (as applicable) to take advantage of the added benefits.

Is there always a V1 API parity for V3 APIs and vice versa?

At this time, there is no V3 parity for every V1 API published in Developer Connect. However, the V3 library is always growing as we continue to enhance existing services.

Any new “/Encompass” APIs that are created for Encompass UI or SDK parity or for an entirely new feature set will be added only to V3 and may not always have a V1 counterpart.

Are V1 and V3 both "stable" versions?

Yes, both versions are currently stable and supported by ICE Mortgage Technology.

Are there any plans to sunset V1 Loan APIs?

Although there have not been any formal announcements of sunsetting the Loan V1 APIs for cases where there is V3 parity, overtime the V1 APIs will be deprecated. At this time, both API versions are supported by ICE Mortgage Technology.