How to API

Automate. Don’t copy/paste.

Workers all over the world spend time copying and pasting data from one software system into another. There are three reasons this makes me weep:

1. Boredom is not a sustainable employment model.
2. It takes forever to get results.
3. Human error is a real thing.

In many cases, it’s unavoidable to keep data in two separate systems. Perhaps your customer relationship management software needs data from your customer service platform or your fulfillment platform needs to send data into your enterprise resource planning system. Since the nerds at Fivable build custom software, we frequently need to get data into 3rd party off-the-shelf systems from the bespoke applications we’ve constructed for our clients (or vice versa). Whatever the reason, it’s obviously better to let a computer automate that data sharing step.

API Flows

As you start asking your development team or software provider questions about transporting data from one system to another, they’ll start talking about 3rd party integrations, APIs, SDKs, or web services. There are a few ways to integrate these systems:

Endpoints and Hooks

The capabilities of the systems involved, the number of systems that need integrating, and whether you’re already using a custom solution dictate the style of integration you’ll perform. As you’d expect, these diagrams are an over-simplification of what a real integration looks like. Some integrations have hundreds of connection points. Each of those connection points can operate in a few different ways. An endpoint is a resource on an API or web service that provides read or write access to a specific kind of data. A hook is a way to register an automated notification of some event to a 3rd party system’s endpoint. Here are some examples:

In general, an event in the system triggers data to be sent to an API endpoint to send or request data to or from a 3rd party system. Those events could be the completion of a form, navigation to a specific user interface, a request for a data report, or a host of other things. A hook is a way that third party systems can limit the amount of programming that needs to be done to customize integrations with their system – but still allow those customizations.

API Risks

APIs often fall short of expectations. Here is a list of risks and vulnerabilities – things to look out for as you perform due diligence on systems on which your software might rely:

• Poor documentation: Many APIs are not as well documented as we would like. Sometimes endpoints are missing entirely, methods have been deprecated since the last revision, or a clear order of operations to accomplish a workflow is not defined. Even some really big companies are guilty of this.
• Customization Requires 3rd Party Programming: Not all APIs support the idea of using hooks in their APIs. Perhaps they haven’t encountered a compelling use case to justify exposing a way to define hooks. This means that if you need to trigger a request to your system from someone else’s, it might require their developers doing some heavy lifting to make it happen. This is very common – so be aware of it.
• Limited Support: Sometimes your programmers will be much better programmers than the ones who built the API. When that happens, it’s common to encounter problems that are very difficult to troubleshoot because you typically won’t have visibility into the other party’s system to debug.

Many APIs (both well-known and small niche systems) have these shortcomings. But if you need to build your own API and you care about your developer users, keep these three vulnerabilities on your radar to make your system worth using.

But do you need your own API?

Maybe. If you think integration through distribution partners or a sophisticated ecosystem will be a part of your business model, it’s worth some exploration with your software team to figure out what it would take to build a really flexible API into your system. And if you build it, build it like you care about developers. Because you do, right?