APIs have become ubiquitous in modern technology - and in modern tech marketing. If you’ve ever looked into buying a software service or platform in the last ten years, the odds are that a good API was listed as one of the selling points. But what exactly makes an API “good?”
Before we dive into that question, let’s take a minute to recap what APIs are, and why they’ve become so central to business and technology.
API 101: What is an API?
Application Programming Interfaces (APIs) are the mechanisms that allow computer software to communicate with each other. APIs ensure that when one software system makes a request, another system can understand the request and respond correctly. When discussing the relationship between two software systems, the application sending the request for action is called the client, and the application sending the response is called the server.
For example, your bank’s software system houses all of your banking data–that software system is the server. The banking app on your phone is the client. When you initiate actions in your banking app, like making transactions, checking your account balance, or even chatting with a representative, the app communicates with the bank’s software via its API and tells it which action to perform. The server provides an API for the client to use to perform actions.
How does an API work?
Let’s say that you want to make a transfer of funds from your checking account to your savings account. You open your banking app and navigate to the transfer tab where you are asked which account you are transferring from, which account you are transferring to, the amount you want to transfer, and any additional notes before you can submit the request. Within seconds of submitting your request, the number on your checking account decreases and the number on your savings account increases, and the physical amount of money you can withdraw from the bank for both accounts has changed.
For this to happen and money to actually be moved, the app needs a way to tell the bank’s system what to do. That is where the API comes in. The APIs are the rules and protocols that are coded into both systems as a set of predetermined requests and responses.
When you enter how much money you want to move and where you want to move it to, the client communicates with the API on the server. When the server receives that request, it reads the information and executes a predetermined set of actions to move exactly the amount of money that you requested into the correct account.
From a technical standpoint, APIs consist of two main components: an address and a body. The address, also known as an endpoint, tells the data where it's supposed to go (in our example, the bank’s system). The body is the data that will be delivered to that address.
Why are APIs important?
APIs allow developers to automate functions and create a very clear, easy-to-understand relationship between what the user needs to do and what the computer systems will do in response to their requests.
Without APIs, the modern conveniences of apps, digital transactions, and the like couldn't exist. Everything would require human, manual interference. Instead of quickly logging into an app on your phone to make a transfer of funds, you would have to physically go into your bank or talk to a teller over the phone, and your request would take much longer to process.
But because of the code and predetermined actions built into digital systems through APIs, users can interact with services much faster. You can transfer your money in seconds, and the bank can gather your information, automate manual processes, and make their work more efficient.
What Makes a Good API?
Now that we’ve established what an API is and why they are important, let’s talk about what makes a good API. While all APIs follow the same principle of allowing systems to communicate, not all APIs function equally well. The quality at which an API is developed impacts how effective any system will be at actually doing what the user is asking for.
So what makes a good, well-constructed API? Here are 5 aspects of a good API.
1. Simplicity
First and foremost, APIs should be simple. This means having clear addresses, endpoints, and easy-to-understand request body structures. In our banking example, the bank’s software and the app’s software are presumably owned and operated by the same company–the bank. Oftentimes, however, the client and the server belong to different companies. Developers at both companies will need to build their systems to be able to understand the API and react accordingly. A simple, straightforward API structure makes it easier to correctly implement.
Let's take a look at an insurance API example. Say that you own a pet store and you have partnered with an insurance carrier to offer embedded pet insurance to your customers. In order for your customers to purchase insurance from you, they have to enter their information in a form on your website. Then the insurance company receives that information, makes an underwriting decision, and issues the policy.
In order for the insurance company to receive your customers’ information and take action on it, your front-end systems need to communicate with your insurance partner’s system. The set of requests and responses between these separate systems should be simple and clear. The simpler the API, the faster and more seamless the integration between these two systems will be, and the fewer opportunities for mistakes.
2. Complete, inclusive functionality
A good API should be able to execute all (or at least most) of the functions a user would need. Going back to our bank example, an app that allowed the user to check their balance but not to transfer funds wouldn’t be very useful to the customer. To be effective, the bank’s API needs to be able to handle most of the things a customer might want to use their bank app for.
For more complex functions, it’s important that an API be able to collect and process all of the information needed to return a response. For our pet insurance example, let’s say that in order to decide to issue a policy, the insurance company needs ten pieces of information from the customer.
If the API could only handle five of those pieces of information, the rest would need to be submitted separately (likely over email or a phone call with an insurance agent). It would be an inconvenient experience for both the customer and the insurance company, and increase the likelihood of manual errors. A good insurance API would be able to collect and process all information needed to issue a policy, right from the app or website.
3. Useful error handling
Errors are inevitable with any piece of software. What sets a good API apart from a bad one is how it handles errors when they arise. Good error handling can make the difference between getting back on track quickly, or getting bogged down in bug reports.
Broadly speaking, there are two kinds of software errors: 400 errors and 500 errors. The difference between the two is how much information they can give about what’s gone wrong.
400-type errors are specific errors with an identified problem. One of the most familiar is a “404 not found” error, which occurs on the web when a user tries to navigate to a web page that doesn’t exist. If you’ve ever mistyped a URL or clicked on an old link to an inactive page, you’ve seen a 404 error. Because 400-type errors give a specific reason for why the request failed, they also give direction on how to go about fixing the problem.
500-type errors, on the other hand, are much less clear. 500 errors indicate general server failures, crashes, or bugs. These tend to be more frustrating for users and developers alike, since they don’t contain much to go on for how to fix it.
A good API should be able to produce mostly 400-type errors that identify the problem so that it can be easily tracked and fixed. When an API produces a lot of unidentifiable 500 errors, it indicates a poor-quality API.
4. Thorough documentation
While not technically part of the API itself, good documentation is essential to a successful API. As developers integrate systems or build the API rules into an app, documentation has a direct impact on how quickly they can work, and how well they can avoid errors. Good documentation should specifically describe each of the endpoints, what the requests should contain, and what the responses will contain.
In many applications, an API will touch various parts of an overall system. This is especially true for more complex operations like our pet insurance example. On the user’s side, applying for insurance might seem like a straightforward software operation - they fill out the form, and the software sends it. On the insurance company’s side, however, it’s much more complex.
When the user submits their application, numerous parts of the insurance company’s system will be involved with the process. One part of the system will document the personal information they provided in the application. Another part will use that information to make calculations around premium costs, and still another part will generate the policy itself. In order to make sure this all happens seamlessly, developers need access to comprehensive, up-to-date documentation for how all these components interact and are executed via the API.
5. Fast performance
Finally, a key benefit of APIs in general is speed. Rather than trudging through manual processes, APIs are meant to automate functions that would take much longer if human interactions were required. A good API should allow information to be passed between servers quickly and efficiently.
Going back to our earlier examples, no one wants to sit and wait to see if their bank transfer request or their insurance application was successfully received. For the best user experience, APIs should process requests in less than a second. If an API is slow to respond, it may indicate inefficient architecture, or that the servers are housed on insufficiently powerful hardware.
Get to know the Boost API for insurance
APIs allow businesses to function in a modern, technologically savvy way. By continuously improving the communication between client and server systems, consumers have access to a wider variety of digital transactions and services than ever before.
If you want to learn more about Boost’s API and how we can help your business stand out through insurance-as-a-service, contact us, or dive into building your insurance program with Boost Launchpad.
