Contact Us

What Makes a Good API?

By The Boost Team on Aug 7, 2022
8 min read
Learn how APIs work, and the attributes of a high-quality API

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.

Previous articles
The top 3 takeaways from our embedded insurance consumer survey
Embedded Insurance Survey Results: What We Heard From Consumers
Feb 3, 2023
You may have heard that embedded insurance is a big opportunity to grow your business, but are your customers actually interested?  We wanted to get the story straight from the source, and so in Q4 2022 Boost surveyed 650+ US consumers. We asked about their experiences with insurance, how they felt about their options, what mattered most in their insurance purchases, and more.  Here are the top 3 things that we learned from our consumer survey results. [See Full Size] In our survey, a whopping 73% of consumers had either already bought insurance from a non-insurance brand, or would be interested in doing so. While price was mentioned most often, other reasons included brand loyalty and convenience. Trust was another important factor. 62% of respondents were interested in buying financial products from a trusted brand, rather than a bank. For millennials, the number went up to 95%. First movers might have an advantage here as well. 20% of our respondents had never been offered financial products from a retail brand - but they liked the idea. All this is promising news for companies outside the traditional insurance sphere who are looking to build revenue and customer loyalty with embedded insurance. If you can deliver the product and experience consumers are looking for, the appetite is there. It’s hardly a secret that convenience is crucial to customer experience in the digital age, so it comes as no surprise that it was important to our respondents. 59% told us that they’d be more likely to buy insurance if it were offered digitally, as part of a related transaction. Younger consumers were more likely to be enthusiastic: nearly 70% of respondents aged 18-29 were interested in buying insurance directly through a transaction on a retail website. For half our respondents, embedded insurance wasn’t a novel idea. 50% had already bought embedded insurance at least once, at the point-of-sale in a related transaction. For many consumers, insurance is a long-term purchase. 68% of our survey respondents told us they’d had the same insurance provider for at least two years, and 10% had had the same provider for more than five years. For retailers, insurance could also be an overall boost to retention. 62% of respondents said that when a retailer offered protect-your-purchase options, they were more likely to be repeat customers. Learn more about offering embedded insurance in our free guide, or contact us to get started.
Continue Reading
Learn the definition of Accident and Illness pet insurance, and how it can help your business.
What is Accident & Illness Pet Insurance? (Plus: Why You Should Offer It)
Jan 28, 2023
Pet accidents and illnesses are unfortunately common, which can cause considerable financial hardship for pet owners. The average emergency vet visit costs $800-$1500, and pet owners in America collectively spend over $34B annually on veterinary care.  If your business caters to pet owners, this presents a significant opportunity for you to offer your customers a service they need. In this blog, we’ll explain what accident and illness pet insurance is and how your business can use it to grow new recurring revenue and build deeper relationships with your customers. As its name indicates, accident and illness pet insurance is a kind of insurance policy that reimburses pet owners for necessary veterinary costs in the event of an accident or illness (up to a certain amount). Typically, a base pet insurance policy will cover emergency veterinary care, and examinations to diagnose, treat, or operate on a covered injury or illness. This can include things like: Without insurance, these services can cost hundreds or thousands of dollars. It’s not surprising that more and more Americans are considering pet health insurance to ensure they can afford care for their pets.  A standard policy will have rules about what qualifies as a “covered” issue for the purpose of reimbursement. So what exactly is considered an “accident” and what is an “illness?” The answers may seem obvious, but knowing the precise definitions can be important. If a pet owner needs a service that falls outside of those categories, they would need to add it as additional coverage in order to receive those benefits.  An accident is usually defined as something like “a sudden or unexpected event that causes injury to the pet." For example, if your cat is injured by another animal, or your dog eats a box of chocolate and needs emergency vet care. Events like these would be defined as “accidents” and be covered by most accident pet insurance policies. It should be noted, however, that if the owner causes intentional harm to their pet, that would fall under abuse and would generally not be covered.  An illness is usually defined as something like "any change to the normal healthy state of the pet, a sickness, disease, or medical condition that is not caused by an accident.” An example of an illness that would typically be covered by illness insurance would be something like heartworms, canine flu, skin rashes, diabetes, or arthritis. Due to cost and complexity, however, cancer treatment is often excluded from accident and illness policies.  The distinction between the accident and illness is important, because it can affect whether a pet’s care is covered. Many standard pet insurance policies cover both accident and illness, but there are policies that may only cover accidents. It’s important for potential policyholders to understand what they’re getting, and if it’s a good fit for their needs. Unfortunately, the short answer is “no.” As a general rule, if a pet has a pre-existing health condition, treatment for that condition will usually not be covered by the insurance policy. However, a pre-existing condition will not necessarily disqualify the pet from being covered entirely. For example, if a dog has pre-existing allergies, and his owner purchased a pet insurance policy for him, any treatments related to his allergy likely wouldn’t be covered. If the dog contracted heartworms after the policy was purchased, however, his treatment could be covered.  This is great motivation for pet owners to get insurance when their pets are young. When it comes to purchasing medical protection, “the earlier the better” very much applies, because as pets age, they are more likely to develop conditions. If a pet owner waits until their pet starts to show symptoms, it can be too late to get the financial protection they need.  Insurance needs will vary for every pet, and sometimes those needs fall outside of standard policy coverage. Some pet breeds have a higher risk of conditions requiring long-term care – while for others, the biggest risk is playing too hard at the park. To accommodate for those differences, pet owners can choose to add endorsements to their policies, such as:  Even more comprehensive policies might cover loss and theft, kennel/boarding services, or even advertising a missing pet and offering a reward for its return. Depending on the provider, pet owners can fully customize their policies and make them as robust or as simple as they need, which can save them thousands of dollars.  Now that we’ve seen how valuable accident and illness pet insurance can be for pet owners to have, let’s briefly talk about the opportunity that this product offers for pet-related business owners. There is an increasing demand for pet insurance in the United States. Since 2017, the average annual growth rate of insured pets is 21.5%. At the end of 2021, close to 4.41 million pets were insured, a 28% increase since 2020. In 2022, the total premium revenue for pet insurance was nearly $2.6 billion. That is a huge market with a promising annual growth rate.  White-labeled, embedded insurance can be a big opportunity for pet businesses to tap into that market and build new streams of recurring revenue. If your clientele is primarily pet owners, you are perfectly positioned to offer this product. Accident and illness pet insurance would be a natural addition to your product lineup, and because your customers already trust and have a relationship with you, they would be more inclined to get the coverage they need from you instead of an insurance company.  Insurance is a very “sticky” product. Due to the nature of insurance, it establishes an ongoing relationship with your customers through monthly premium payments. Not only would you have the benefit of that recurring revenue, but you also have the ongoing brand exposure that it provides. It gives you another touch point with your customers, which can only strengthen your long-term relationships with them. Modern customers expect modern experiences. Traditional insurance carriers and policies tend to be rigid with a mixture of slow offline processes and archaic online ones. By offering your customers a customizable, convenient, and entirely digital solution, you can meet your customers in the 21st century and stand out from the competition.  Embedded insurance, as its name implies, is insurance that is embedded into an existing purchasing experience–it allows your customers to buy digital pet insurance without requiring them to leave your website to complete the transaction. Another example of embedded insurance would be travel insurance for an online plane ticket or crypto wallet insurance offered on a crypto-related website.  A white-labeled insurance product is one that is completely integrated not only into your website, but also into your brand. If you were to offer white-labeled pet insurance, your customers would have no indication that the product was not created by your company.  Embedded pet insurance is a great opportunity for pet business owners to grow their revenue and deepen their customer relationships.  If you are interested in embedded accident and illness pet insurance, Get the Guide to Growing Your Revenue with Embedded Pet Insurance, and learn everything you need to know to get started.  If you’d like to speak to one of our pet insurance experts, contact us to learn more.
Continue Reading
Insurance billing 101
Insurance Billing 101
Jan 23, 2023
The insurance market is huge and growing. But when it comes to collecting those payments, insurance is a lot more complicated than most goods or services. We’ll take a look at the factors that go into calculating an insurance bill, and what options companies have for billing methods. The reason why insurance billing is so complicated can be boiled down to one thing: state-by-state differences. Since every state makes its own rules for insurance, the requirements to stay compliant can vary significantly. Businesses that sell insurance in multiple states need to pay close attention to each state’s rules. Here are 5 things that can make billing for insurance complicated: Every state imposes its own taxes and fees, sometimes with different guidelines for how they should be collected. This means that if you sell insurance in fifty states, you need to stay up to date with fifty sets of rules for when and how to add taxes to your customer’s bill.  Different insurance products can also have their own rules, depending on both the type of product and its regulatory status. Admitted products, which are products that have met regulations set by the state’s Department of Insurance, have most (but not all) taxes and fees included in the premium. For non-admitted products, however, taxes and fees are billed separately.  Taxes and fees can cause complexity for more than just the policyholder’s bill. Some are commissioned on, meaning that they’re included in the amount calculated for an insurance seller’s commission, and others are not. This is yet another set of rules an insurance organization needs to track in their billing.  Besides just having different rules about how taxes can be charged, different states may have differing rules about how to charge for the premium itself.  As we saw earlier, the premium is the cost of insurance for the entire coverage period, frequently six months or a year. Going back to our earlier example: say an insurance policy covers a 12-month period for a premium of $600, with an additional $120 in taxes and fees. Depending on the state, the premium might be billed a number of different ways: If the insured doesn’t pay their premium, what happens? The answer depends on the state. Usually you’ll send a notice that their policy will be canceled on a certain date unless they pay their bill, but the way that notice is sent may be dictated by state requirements. Some states mandate much longer notice periods before a policy can be canceled for non-payment. States may also have specific requirements around the language used in the notice, and how it’s delivered to the policyholder.  If the policyholder cancels their policy partway through the term, they may be entitled to a refund. The amount of that refund, however, can be complicated to compute.  If the entire premium was paid upfront, how much of the term has passed? The appropriate amount to refund might vary if the policyholder cancels near the beginning of the month, versus near the end. Refunds might also be prorated to account for the part of the term that’s already over, in which case the amount refunded might vary based on the day of cancellation. Even the time remaining in the term may not be straightforward to calculate - different insurance products use different calendar types, and the number of days in a “year” or “month” can vary.  Separate from the premium are the taxes and fees. Depending on the situation, these may or may not be part of the refund. Some taxes and fees are considered fully “earned” at the beginning of the installment period or at payment - which means this amount would not be returned to a policyholder who cancels early. Determining which taxes and fees are included (and which aren’t) is an important part of any insurance refund calculation. Any time an insurance policy’s coverages change, the premium amount changes too. If it comes time to renew a policy and the insured decides to add or remove coverages, the billing is fairly straightforward - the premium for the next period will reflect the new coverages.  If the policyholder wants to add new coverages before their policy term ends, however, it’s called a midterm endorsement.  This is where things can get complicated, especially if the policyholder has already made payments toward the old premium amount. The difference between the old and new premium will need to be charged or refunded to the policyholder as a reconciliation. This isn’t as simple as just charging the difference between the old and new premium. The amount required for the reconciliation will depend on the time left in the policy, the amount already paid, and more. We’ve looked at some of the factors that add complexity to calculating an insurance bill. However, determining the amount owed by the insured isn’t the end of it. There are multiple methods for how the policyholder’s premium can be collected. The main reason for this relates to how insurance is sold. Many companies that sell insurance, like insurtechs, don’t build their own insurance product in-house. Instead, they partner with another company that’s already done that work to offer their product, whether that's an insurance carrier or a white-label insurance-as-a-service provider These companies then have two options for choosing a billing method: direct billing, or agency billing. In direct billing, the policyholder pays the insurance carrier directly. With this form of billing, the company that sells the insurance is paid a commission after the carrier has received the premium. With direct billing, the insurance carrier is responsible for all the billing issues we discussed previously, from taxes and fees to refunds, cancellations, and premiums. This can make it significantly easier for the company selling the insurance to get started, as they don’t have to build their own billing function around the product.  Because the carrier or insurance-as-a-service partner already has a functional billing system for the specific insurance product being offered, all the distributing company would need to do is build an integration to their partner. This can mean a substantial increase in time-to-market with a new insurance product. With agency billing, the policyholder makes payments to the insurance distributor (i.e., the company selling the insurance product). With this form of billing, the distributor collects the commission upfront and makes retroactive, monthly payments to the insurance carrier. With agency billing, the company selling the insurance is responsible for calculating the amount owed, including taxes, fees, and any refund issues. The distributor is also responsible for the actual collection of money, which means they either need to integrate with a payment platform or build one from scratch.  This isn’t necessarily a hurdle; businesses that sell goods or services online likely already have integrated billing capabilities that allow them to accept digital payments. For example, a business that sells pet products online would already have online payment infrastructure, which could likely be used for embedded pet insurance. This has the added benefit of keeping all of the company’s business data in one place. However, some payment platforms can present user experience challenges, like policyholders having to re-enter personal information on the payment platform, after already providing it on the insurance application. For businesses that aren’t yet set up to take payments, this is a function that would need to be built out before offering insurance with the agency billing method. In almost all cases, integrating with a best-in-class payment platform will be faster and more cost-effective than trying to build a proprietary billing system in-house. If you want to learn more about insurance-as-a-service through Boost, contact us, or dive into building your insurance program with our comprehensive guide.
Continue Reading