If you use the Internet, you will, at some point, have come across an Application Programming Interface, or API.
Tech companies – from FAANG-sized behemoths to one-man-band tiddlers – use them internally (to ingest data, share it with partners and make their in-house workflows more efficient); and in their products for customers (e.g. Gmail’s API allows users to create their own email client). Some companies have built entire business models out of managing APIs.
At Windward, we’ve built APIs to make our working lives more efficient; and we use external ones that help us pull in data from our partners – my old friend weather data being a case in point.
At their best, APIs can be indispensable. Build a bad one or pick the wrong one, though, and they can torpedo software development, wasting time and money while the company struggles to make it work. In some cases an API can be the difference between a company’s success and failure.
Given their importance, I would suggest you consider the following when deciding to work with an external API:
- Limitations – understand them and how they affect your requirements:
Building and maintaining an API requires computing and networking resources; the more popular the API, the more resources it consumes. This is why most APIs will limit your calls in some way (and may charge you according to the amount of data used). Some will apply an Hourly/Daily/Monthly limit, which could be per IP or customer. Others will limit requests or response size. Others may impose additional restrictions on what you, as a consumer, are allowed to do. It’s important to understand each API’s limitations, and how they will affect your company’s needs and data availability.
- Throughput: Even though the API provider will usually limit your calls according to your payment plan, there may also be additional limitations. For example: if an API allows me one million calls a month, consider what would happen if you decided to use all that bandwidth in one second? It’s possible (and quite probable) the API’s hardware and network wouldn’t be able to handle it. So in addition to the limitations discussed in the previous paragraph, it’s also important to understand the actual Mbps (MegaBits Per Second) bandwidth of the API provider, in order to be able to use it efficiently, not to crash it, and be able to throttle it if needed.
- Ability to scale: When you start working with an external API provider, it will be able to support an agreed upon traffic bandwidth (as discussed above). But what happens if in the future you need more? It’s important to understand the API’s scaling abilities, and if it will be able to cater to your future needs.
- Message Structure: There is no common, agreed-upon structure to messages sent and received by various APIs. Each company sets its own standards. Some may send responses in XML or JSON; others in less common (or even proprietary) formats. So make sure you understand exactly how each API works and if this is appropriate for your needs.
- Response: Another important issue is the way API returns the response. It’s important to know the way an API returns responses, to be able to understand how this would coexist with your existing system design. The most common ways APIs return responses are as follows:
- HTTP blocking call – a consumer service sends a request to the API, and then waits for the API to generate and send a response (while keeping the connection open).
- Callback – a consumer service registers a callback address with the API. Each time a request is sent to the API, the connection is closed as soon as the request is received. When the API finishes generating the response, it sends it to the callback address.
- Documentation: One of the most important elements that differentiates APIs is how well documented they are. Some have minimal documentation, or no documentation at all. Others have entire domains dedicated to their documentation, or thriving online communities that happily share knowledge. I suggest you choose an API whose documentation makes you feel comfortable, and will be able to to help you handle any problems or future needs as they arise.
One final thought: even if you go through the entire checklist and everything clicks, so to speak, you still need to be prepared for the fact that this isn’t a Catholic wedding: your organization’s needs may change, and with it the API you use. So plan accordingly, and write your code generically enough to be able to continue working, even if tomorrow’s API is not the API you choose today. Do this, and APIness shouldn’t be hard to find.
Alex Milman is a Senior Backend Developer at Windward
