Working with numerous third party APIs can be a headache. Damon Swayn of InSite should know. The InSite team has integrated countless APIs for its clients’ CRMs into its platform. Damon over at his Medium blog gives you the top four lessons he and his team have learned.
Working with numerous third party APIs can be a headache. Damon Swayn of InSite should know. The InSite team has integrated countless APIs for its clients’ CRMs into its platform. Damon over at his Medium blog gives you the top four lessons he and his team have learned from working with third party APIs so you can build APIs that delight rather than frustrate clients.
Lesson one. Documentation is key. Damon admits it can seem like a waste of time to worry about how other companies will access your data. But clients are likely at some point to ask you to provide your API to a third party. If the documentation is weak, the client will let you know and it could cost you.
The second lesson is one that is more relevant today than ever. The trend in web development is to have all the rendering done on the browser and fetch content from the backend via an API. This can tempt developers to simply repurpose their existing internal APIs for third parties. Don’ t do it. These internal APIs are designed for interacting with a frontend JS app. They’ re not suited for third party server-side apps. Damon gives the example of one CRM InSite integrated where to get data on a contact they had to make a call to an event-stream API that returned the HTML of marketing email correspondences. It was a real pain to extract the 5% of useful information for the team’s purposes.
The third lesson is: remember that polling is not ‘real-time’ . APIs are designed to give a snapshot of data at a point in time. This means if you want a real-time integration the best you can do is polling. Most APIs aren’ t designed for polling. Some make it a little easier by offering a way to filter results to what has changed since you last accessed the API. But most don’ t so to implement polling you’ ve got to store and keep track of what data is being returned by the API and filter out the unchanged data. A better solution according to Damon is to create some RESTful web-hooks that trigger when a record is created or updated. You can then provide a callback URL to receive a POST request on triggering the callback. This way, the webhook receiver will get the change in data in as close to real-time as possible.
The last lesson is log, log. Integrations are effectively distributed systems, which are famously a pain to debug. You can do all the testing you want, you’ re still going to miss things like catching an API changing a JSON key or dropping an HTTP header. Logging lets you catch issues but even better it allows you to inspect data before and after the API call to find what exactly caused the problem.
