Tech Talk: Why Choose an API as a Product?

Ok cool. Now we know what APIs are, and what they do. So why choose an API as a product?

APIs have become largely ubiquitous in the tech landscape, and for good reason. However, it’s important to understand that there are alternatives and it’s equally important to understand why we don’t choose those alternatives.

In reality, there are a vast array of alternatives to APIs, but here we will discuss two of the most common: software suites and direct integrations.

A suite of software comes in the form of a program that is delivered and installed on the user’s computer (e.g. Microsoft Office) and provides a full set of functionality directly on a user’s computer. Going this route has some significant advantages over APIs:

1. The distributor of the software has an increased level of control over interaction with their backend systems
2. To understand this, think about how Slack distributes an application, but in reality it still calls an API behind the scenes. Slack has ultimate control over how that API is used by the software they distribute because they control both sides of the communication.
3. Empowers creation of more complete feature sets
4. Having more control over communication via the API allows for building features on top of the API that would otherwise be up to the user if they did not have a suite of software to use.

However, suites of software also have significant disadvantages when contrasted with an API:

1. Larger engineering effort is needed for the distributor of the software
2. The distributor of the software needs to build and maintain the suite of software that is being provided to users.
3. Delivery of software is challenging 
4. The distributor of the software needs to actually distribute the software. How do you get the software to customers in a reliable way? How do you make it simple to install and properly set up?
5. Maintenance becomes complex
6. With a suite of software, the burden is on the user to update and maintain the software installed on their computer. Often, users will not update their software, leading to a long tail of versions that need to be supported and maintained, including all the bugs and lack of features that may have been addressed by newer versions.

Direct integrations often have similarities with APIs, but the key distinction is that each new user is individually and specially integrated with the parts of your systems that they wish to use. The advantages over APIs here are:

1. More control over the integration process
2. Each integration is done as a one-off, in a hand-holding manner, which allows for frequent and in depth communication between the user and the owner of the system. Issues and difficulties are better understood and easier to fix because they are encountered by both sides in tandem.
3. No need to build API request and response handling
4. Recall that APIs define the rules for communication by defining a set of requests that can be sent and a corresponding set of responses to be sent back. These requests and responses need to be handled and translated before the necessary work can actually be done. When two systems directly integrate with each other, there is no need for this translation and handling layer.

Again, direct integrations are not without their disadvantages compared to APIs:

1. Large onboarding effort
2. Direct integrations give us more control over the integration process, but that comes at the expense of the time and effort spent helping each individual user with an integration for their specific needs.
3. Less control over how user interact with systems
4. APIs allow for restricting users in what they can actually do, which empowers them to do more by making what they can do and how to do it far easier to understand. When a user is given control over a direct integration, they are free to do just about anything they wish, which is usually to the detriment of themselves and the owner of the system.
5. May require use of APIs anyway
6. Direct integrations are messy and time consuming, which is often mitigated through the use of APIs. However, this usually results in an API for every single user catering to their specific needs. This ultimately begs the question: why not just have one API that fits everyone’s needs?

Now that we’ve stated a strong case for API as a product… What makes an API “good”?

A “good” API is a bit nebulous and will often lead to a spirited debate amongst engineers, but while they may disagree on what these qualities look like in an API, most engineers will agree that a “good” API has the following characteristics:

1. Easy and simple to program against
2. This is somewhat self-explanatory: the simpler an API is to use, the more people will use it and the more complicated an API is, the more people will give up trying to use it.
3. Requires the minimum number of requests to do the maximum amount
4. This is part of making an API simple. Most requests in an API could be broken down into a much larger, finer grained set of requests. While this might provide more functionality, it makes the API more complicated. The caveat here is that going crazy with request consolidation can make an API less usable, so it’s about finding a balance.
5. Minimum complexity for maximum functionality
6. This speaks to the caveat of the last point: we want minimum complexity but not to the point that we remove important functionality.
7. No superfluous functionality
8. As we’ve learned, APIs are extremely simple and are in reality very easy to build. This can make it tempting to add every single piece of functionality you can think of, with the thinking that more functionality means a better API. This line of thinking quickly leads to what is known as API bloat. You’ve added so much functionality to your API with the goal of allowing everyone to do everything, but it’s not so complicated that no one knows how to do anything.
9. Low maintenance costs for the user
10. Users of the API should be able to implement sending requests and receiving responses one time and then be done with it. Of course, this may change if new functionality the user needs is added, but the API as they have integrated with it should always work. There should not be any breaking changes.
11. Documentation, documentation, documentation
12. If we recall what an API actually is, just a set of rules for how two systems communicate, it becomes clear that an API is really just documentation at its core. It doesn’t need much explanation to say that you can’t have a good API without good documentation.

Phew. We’ve covered a lot of ground here. But wait, there’s more! In Part 3, we dig into the Particle Health API. In the meantime, why not take a look at our use cases here, or try out Particle here?

And if you have questions— we have answers. Just contact us anytime, here!

‍