Plans are a foundational resource in our public API and apart from Clients, probably the most important to our customers. Plans, as a concept, model the many varied financial products available in the market, both advised and non-advised, so in addition to being central to what our customers do, they are also fairly complex as a result.
We released our first public plan API in the summer of 2017. It was and remains in beta status as the API was only partially complete. It covers a good portion of investment (and later mortgage) plans types, but the remainder of the plan types and related fields have been a noticeable gap since then and something our community frequently ask about.
We have been very busy in the background, working to fill this gap and we are now at a point where we feel we can share some of what we have done with you. The primary reason it has taken some time to get to this point, is that we have had to rethink some of our original ideas of how we model plans in our API, to ensure the resulting resource is easier to understand and more intuitive to use given its size and complexity.
To do this, we will be introducing a new version of the plan API which will exist alongside the current API for a period of time. Crucially, this avoids making any breaking changes to the existing API during a transition period, but more on this later.
This post will introduce you to the new version, how to transition from the existing version and what to expect in terms of the future road-map.
The new model
The existing version of the plan resource uses a flat composition approach to introduce the various plan types, i.e. there is a base Plan object and each category of PlanType, such as investments, was an optional property structure off that. This worked initially but as we worked through new plan types, it became evident that without a true hierarchy the model would become awkward and complex to use.
The new model which forms the basis of the new API version now uses a true inheritance hierarchy, which will make the model easier to understand and manage. We have endeavored to minimise the changes to existing fields, although we have had to make changes to support the new model and taken the opportunity to improve a few things at the same time. We will provide documentation that should make the transition fairly simple, but I'll cover transition aspects later on in this post.
Below is the proposed Plan model hierarchy:
The model above maintains a base Plan type, albeit it now becomes abstract in the sense that you can't actually create a Plan and it does not represent a specific PlanType.
We have extended that base type into a further 3 key abstract sub types of Assets, Protection and Liabilities, again these are abstract and do not represent PlanTypes. These sub types are then finally extended to introduce a 3rd layer of concrete sub types that will now form the basis of all of the PlanTypes we offer on our platform. These are the objects that you can create via the API.The exact abstract sub type groups are still to be confirmed as new sub types are released.
In terms of using the API, consumers will largely be concerned with the layer 3rd layer concrete types in the hierarchy for any write operations, but may choose to use any type in the lineage for read or aggregation use cases i.e. they are polymorphic.
What is going to be released and when?
This first release of this new model will include the schema changes as part of a new API version but will keep field parity with the existing version. New fields types for Liabilities->Mortgage will be a fast follower and all the other types and fields will follow incrementally thereafter. We are targeting to be feature complete, in terms of all plan types and field coverage, for Q2 2019.
We also added support in our documentation, to allow hierarchies to be easy to navigate and these changes will be released together with the first release.
Which version should I use and what happens to the old one?
The old API version will be deprecated, however if you are currently using it, don't worry it will still continue to work after the first release without any changes on your side.
The new version of the API can be used by passing a header X-Iflo-ApiVersion with a value of 2. If you do not pass this header value, by default you will be using the old (existing) version. This transition phase will continue for 3 months after the first release. Once 3 months has elapsed the default will change to target the new version 2. If you still wish to use the old version of the API you can do so for a further 3 months by passing the X-Iflo-ApiVersion with a value of 1. We recommend you start passing this header as soon as you can, as being explicit, in terms of which version you are targeting, will help you avoid any surprises during this transition phase.
We highly recommend that you transition to the new version as soon as possible as once 6 months is up or once we see no one using the old version (whichever comes first), we will be removing support for the old version "1".
If you are planning to use the Plan API for the first time, you should use the new version.
Note: header versioning is complementary to the existing URI versioning technique and not a replacement. We chose not to increment the URI version as we are still in beta for this resource and we did not want to impact on the many hypermedia references in other APIs that point to the /v2/*/plans/... etc.
What do I need to do to transition to the new version?
As I mentioned above we have tried to minimise the impact and so although the new version introduces breaking changes they should not be too difficult to adopt.
I have listed the notable changes and any new features or fields being introduced in the first release below.
Note: You should consult the API documentation, after we publish the release, to ensure you have the most up-to-date information before you start any development work.
Inheritance Structure
This is the key structural change for this release. It involves each type in the hierarchy being identified by a discriminator property such as "MortgagePlan" for all mortgage related PlanTypes. This means that instead of the mortgage related field being in a structure under a mortgage property, they are now flattened and combined with the base plan type fields. Since we only released investments and mortgage, these two are now being removed and incorporated into the hierarchy as per above.
Old version:
{
"id" : 123,
...//all other base plan fields
"mortgage" : {
...//mortgage related fields
}
}
New version:
{
"id" : 123,
"discriminator" : "MortgagePlan",
...//all other base plan fields
...//mortgage related fields
}
Base Plan field changes
- adviceType - field is renamed to lifecycle to avoid confusion
- parentTopupPlan - field is renamed to parent as this is the parent plan for both topups and wrappers
- isVisibilityUpdatedByStatusChange - field is removed as it is internally significant only
- isVisibleToClient - field is removed as it is application specific
Mortgage field changes
- outstanding - field will be removed as it was a duplication, use latestValuation from the base plan type as the current outstanding balance.
- property.address - this object is changing to point to the address API as hypermedia rather than the address itself.
- property.value - this will now become readonly and pull in the value from the current asset valuation linked to the mortgage.
- loanToValue - this will be made readonly as it will now be calculated from dividing totalLoanAmount by the price valuation and shown as a percentage.
- term.remaining - this will be made readonly and calculated by subtracting the current date from the plan start date and adding the mortgage term.
- term.initial - this will change from years to months to simplify calculations that previously involved fractions of years.
- term.capitalRepayment - same as above
- term.interestOnly - same as above
- repayment - this will be made readonly and will be deprecated in a future release. Use contributions instead.
- fee - renamed to lenderFee to avoid ambiguity.
Investment field changes (and some new ones)
- lumpSumContribution - this is being removed, use the associated contributions instead
- maturityDate - this is being removed, use endsOn field instead
- maturityLowValue - new currency field for projected maturity value with low growth
- maturityMediumValue - new currency field for projected maturity value with medium growth
- maturityHighValue - new currency field for projected maturity value with high growth
- maturityProjectionDetails - new text field for maturity projection notes
- hasGuaranteeOfOriginalInvestment - new boolean field for marking the original investment amount as guaranteed or protected.
Timelines and future road-map
The first release is imminent, we are dev complete and the changes are currently in test. We will announce the release in the next few weeks.
As a fast follower we will be releasing all fields supporting mortgage plan types. We are targeting the end of year.
Thereafter we will start to release fields that support PlanTypes modelled by each of the 3rd level concrete types incrementally, until we are done. Although we do not have a priority order or dates that we can share with you now, we will do as soon as we have something available. We envisage being complete in Q2 2019.
Thank you for your support and patience over the last year, we do think these releases will provide significant value and open up new opportunities and use cases for API development. As always, please send us any feedback or issues to development@intelliflo.com
