Best Practices for API Integrations in Enterprise Systems
Application program interfaces—more commonly known as APIs—are increasingly important for building efficient business processes. This is because they allow developers to tailor systems to optimize business processes. They’re also a quantum leap from yesterday's enterprise software tools, which were built and delivered as-is and required endless customization to actually use effectively.
Basically, the API has brought modern software to the enterprise. In today’s enterprise software market, every tool that you use needs a robust API in order to efficiently send and receive data from other systems. Because of the proliferation of tools available, building your own integrations has never been easier—or more necessary.
Here are some tips for how to make sure you’re set up for success.
Best Practices in Evaluating Tools
User experience in an API is just as important as with a graphical user interface. How do you go about choosing a system with a good API user experience?
Documentation: Good documentation—thorough, well organized and easily understood—is a must. When you evaluate software providers, understanding how their system functions, and what happens when either system which you are integrating does not perform as expected, is critical.
Error messaging: Error messages alert the system’s users to issues with data quality or process breakdowns. To get the most out of their capabilities, choose systems with good, human-readable error messaging in their API. This will save you considerable time and effort when problems occur and make for a better-designed, more effective system.
For example, "422 account code is too long (maximum is 50 characters)" is much more actionable than a "422 Unprocessable Entity" If you multiply this by the number of times errors will be encountered, you can save your users a significant amount of time by choosing software with good error messaging.
Understanding limitations: The documentation or the team at a given vendor should be able to supply you with information about rate limiting, deprecation of old versions, and information about scoping requests. If this information is not immediately available, ensure that you ask the vendor so that you can understand the limitations of the system and its API before choosing to integrate.
When using APIs for data integration, it is important to get only the data which you care most about as this will make your calls more efficient and reliable. You also want to pay attention to how data is sorted, as this will affect the data that is returned in the call and may affect the data in the destination system as well.
For example, say you would like to pull Recurly data about new subscribers into your internal data warehouse. Let’s assume you want this data to be updated every 15 minutes. If you query the Recurly API for all subscriptions each time the call is made, that will be a much longer call and contain much more data than what you want, which is subscriptions created or updated in the last fifteen minutes.
With Recurly, the way you make this happen is the following:
Rate Limiting / Data Limits
These days, most systems will limit API traffic. Being aware of these limits, for both systems involved in the integration, will allow you to ensure data is transferred successfully.
When you hit API limits, the best course of action is to examine the calls you are making and see how you can make them more efficient. This may mean sending fewer calls, sending calls less often, or using different methods to send or receive data.
Some systems also impose a cost on the amount of data you store in them. This is important to understand as it may be to your advantage to send less data to this system or to delete data on a periodic basis. This can increase integration complexity, but it will save a lot of time troubleshooting and resolving issues once an integration is implemented.
You want to put a lot of thought into integration before actually building. If you have time to do it over, you have time to do it right the first time. Or, as carpenters say, “Measure twice, cut once.” Understanding the goals you’re trying to achieve should come first. Then, with those goals in mind, you need to understand the capabilities and limitations of each system and its API. And only then should you design the integration. And of course, heavy testing is always strongly recommended before you move into production.