At OneDome we build a platform that serves consumers and businesses from various industries. We often face projects that require an integration with a third-party service. Some of our products act as a melting pot for information that we pull from various sources. While others push collected data into a myriad of external destinations. So far we have successfully established connections with more than 600 systems both in the property industry and outside.
There is one important lesson that we have learned so far. A proper initial research can save enormous amount of time and effort. Usually your project will require to connect to a third party service through some kind of an API. Depending on the use-case you will be either a service provider or a service user, or both. In any of these cases, consider the following questions before you start the work on the final solution:
Push or pull?Ultimately there are two mechanism to send data outside your services. You will be either providing an ability to pull data from your system, or you will push it to an external destination. The same applies to receiving data. You will either pull it from the third party service or provide an interface for them to push it to you. Start by understanding which of these mechanisms are available and what are the implications of their usage in your case.
How does authentication work?It's highly likely that your integration with another service will not happen through a public channel. This means services involved will need to authenticate requests they receive. There are many frameworks and standards that solve this problem. Understand which ones are going to be used in your project. Test connections if possible and ensure that you have credentials. Often you will have two separate sets of credentials for production and development environments respectively.
Is there a sandbox?In many cases services provide a sandbox (or a development) mode which can be vey handy for sending test requests and pulling test data while an integration between two services is built. If you are are acting as the main service provider in an integration think about providing an ability to easily run tests for the external developers. And if you are the service user, research if there's an ability to safely test your solution with mock data.
What are the support channels?In most of integration projects good communications are essential to avoid any friction and unnecessary delays. As a service provider make it clear who are responsible parties on your side. It might be a dedicated support team, a team of developers of the service involved or even one person responsible for the success of the integration project. As a service user, make sure you know who are your main contacts during development stage and further for the maintenance needs.
Are there any quotas or limitations?Many products have certain limits when it comes to usage of their services through an API. It might be directly linked to a pricing plan or a commercial agreement. It can also be there just in order to ensure that the requests do not affect the overall performance. Clarity on this will save you from unpleasant surprises during the implementation work.
How will monitoring and analytics work?Some live connections between two independent systems require automated health-checks or even more sophisticated monitoring mechanisms. Availability of analytics is another common requirement for the integration projects. It might be a live dashboard or an automated reporting emails. It is important to think about these two aspects while scoping a project. The stakeholders who own operations are usually the most useful resources for understanding the context around monitoring and analytics for your integration.
What is the big picture?Additionally, I'd strongly recommend understanding all the services provided by the product you are integrating with, not just the part you need in your project. It's often the case that a related service will help you understand the inherent logic of the entire API by providing some missing context.
The questions from this article will surface surface potential risks for you. This will pay you off by making your implementation stage much more predictable. Once you start the building phase you will be able to focus on the composition and design decisions, instead of handling the unforeseen and inventing ad-hoc solutions.