The feedback we have had, has been largely in three main areas:
- Comprehension - Some APIs were hard to understand or had references to properties that were foreign or confusing
- API Gaps - There were some gaps that prevented common use cases from being realised
- Granularity - Some APIs were too granular and resulted in some use cases being quite chatty
To address these and other issues we have recently made some significant changes to our APIs. The APIs released to "beta" are APIs that we have been using internally for sometime now and will continue to use for awhile more. In order to address some of the feedback and improve our customers experience we have decided to release a set of version 2 endpoints "v2". This means we are not changing or extending any of our existing v1 APIs but producing new improved versions.
Creating version 2 allows us to make significant changes without breaking existing APIs (we use these internally) and doing this now means that our customers can take advantage of these changes immediately and will avoid any later disruption and breaking change.
So whats changed?
After analysis we have highlighted a few key contributing factors to the issues around comprehension:
- Inconsistencies in the semantics or naming of resources and properties
- Some, not so useful, internal fields were being exposed that were causing some confusion
- APIs were not self describing or discoverable
- Lack of sufficient documentation in certain areas
We have started to address these issues with the following changes:
New and Revised Resources
We have released revised versions of the following resources taking care to ensure that we addressed all inconsistencies in naming and removed unnecessary properties to keep them clean and relevant.
- Clients
- Advisers
- Addresses
- ContactDetails
- ServiceCases
- Relationships
- Incomes
- Plans
- Contributions
- Valuations
These are the key resources in our system and the ones our customers have highlighted as the most important ones for their use cases. Don't worry if something is missing, we will continue to add to these over the coming weeks and months.
Hypermedia
We have brought forward a few road map items such as the introduction of hypermedia links to assist in making our APIs more discoverable and self descriptive. If you have not heard of hypermedia or HATEOAS (Hypermedia As The Engine Of Application State), you can read up about it here. In simple terms we are adding a bunch of links to our resource representations that point to other related resources. The idea being that you should be able to better navigate our APIs now that we can show you, directly in the returned results, what you can do next and what is related to each resource. Think about this much like a web page with links that direct you in areas you may want/need to go. We will write a more detailed blog post on this soon to explain what we have done and why for those that are interested.
New APIs and features
You may notice that servicecases and relationships are two new APIs. These were missing in v1 but often requested so we have added those to the v2 set.
Another often requested feature was the ability to search the clients resource. Although we have not implemented deep search (that will come later) we have introduced some simple filtering capability on keys fields, again all based on customer feedback. Look out for our documentation to see how this works.
Granularity improvements
One thing you may be thinking right now is that that list of resources above looks mighty thin. It is, however this is a little deceiving as we have remodeled some of these resources to be less granular and contain more data. This means less APIs to understand, less API calls to make and hopefully allow for more responsive applications.
To explain a bit further we have:
- Removed "party" types from being resources i.e. People, Trusts and Corporate resources - this was too complex and confusing.
- Consolidated full party information into the Clients and Advisers resources - this should avoid many additional calls to get relevant information.
- Consolidated the associated Addresses and Contacts endpoints so that they are accessed from Clients and Advisers resources i.e. v2/clients/addresses, v2/clients/contactdetails, v2/advisers/addresses, v2/advisers/contactdetails
- Included the latest valuation details into the Plans resource so that you do not have to go to the valuations resource to get the plan's latest value.
- Included the advisers name on the client resource so that you do not have to make a separate call to Advisers to get it.
Similar work will continue with all our resources as we move them over to v2.
Developer Hub & Documentation
We believe that self describing APIs should not rely on out-of-band documentation in order to use them, although this is an ideal we will keep pushing towards, we do recognise that there are certain areas where improved documentation will really help our customers. We will be updating and improving this documentation to address key areas that need it in the near future.
Our developer portal will also be updated to show the version 2 resources by default now, as these will now form the basis of what we will enable for the production release. You can still access the version 1 documentation though by following this link.
Domain names
We have moved to slightly different URL template with regards to how environments are refered to. Previously you needed to us the following templates, replacing environment and versions as appropriate:
Sandbox: https://sandbox-api.intelliflo.com{environment}/{version}/{ResourceLocation}
Production: https://api.intelliflo.com{environment}/{version}/{ResourceLocation} Now just a single URL template is used and the environment variable will move to the domain name keeping the URL path consistent, i.e.:
https://{environment}api.intelliflo.com/{version}/{ResourceLocation} Note: All version 2 APIs are addressed using "v2" for the {version} variable and the {environment} variable should now be "uat-" refering to our uat environment eg:
https://uat-api.intelliflo.com/v2/clientsPlease refer to the documentation for further details.
Wrapping up...
We understand that this is quite a bit of change but we felt it was better to do it now rather than later when it would be a lot more disruptive. We are very pleased with outcome of version 2 so far and hope you will be too, some of the changes feel very obvious in hindsight but shows why customer feedback and early access programs are so vitally important to developing useful software systems - we hope ours will be.
Once again a big thank you for all those involved and we look forward to your continued support and feedback.
