What is an API, and why would you have one
Before beginning, let’s establish what an application programming interface (API) is, and more crucially, what it isn’t. An API is a standardized interface for different software components to communicate, generally to fetch data. This definition might seem like an obvious one to make, but people and companies often use the term to mean something more specific. It doesn’t matter if an API is REST or GraphQL based, or you use an esoteric method of your own creation; it is still an API.
For the past few years, when people heard “API,” they generally thought of an HTTP-based REST-architected API, but for most of the internet’s early days, people thought of a protocol-neutral SOAP-architected API. More recently, developers have added GraphQL, gRPC and there are many other ways to call and architect APIs from web-scale to operating system internals.
This article tries to remain as protocol and architecture-neutral as possible but leans towards HTTP and REST, as they are currently the most common options.
An API allows users and businesses to consume services in their applications and services. As the number of interconnected applications enabled by the rise of the internet grew, so did businesses’ revenue that maintained commercial APIs. Businesses such as Salesforce and Expedia make large portions of their revenue from other businesses consuming their APIs, and not from the web-hosted versions of their applications.
1. Reduce the barrier to entry
Revenue does not replace good experience
Many of the rest of the considerations in this article are irrelevant if a provider makes it hard for you to try an API-based service in the first place. While there is definite business value in providing an API, businesses are justified in making money from them; making it hard for people to access is not generally a smart business decision. A provider should offer a free self-serve tier (demo license or limited features) to their API offerings that allow people to sign up and try before they buy, and not need to contact a sales team to experiment.
Documentation
Analyzing good documentation is an entire article in itself, but there are some crucial points to look for.
There is a temptation to rely on a handful of code comments, autogenerate documentation from those comments, or something like an open API specification, and consider documentation “done.” For simple projects, this may be enough, but it’s probably not, as it tells you how the individual tools work, but not how to assemble them into something useful.
At a minimum, there should be a getting started or “hello world” guide, and while it depends on the complexity of your application, you can use the “Time to first hello world (TTFHW)” metric to compare the platforms you are considering.
While not essential (or that common), interactive documentation is a good sign that a provider cares more about helping you understand how to use their API. If implemented properly, it allows you to prototype while authenticated and work with your data.
Authentication
Ensuring a user is valid and who they say they are is an essential step for security, and to ensure a user has access to their data, but it needn’t be overly complicated.
There are several standard processes an API should follow from basic auth to OAuth and using external services (an API!) such as Auth0, but remember that an API cannot rely on stored credentials from a client. Whichever option you opt for, stick to standards (this is a pattern for this section) and again, allow people to self-serve wherever possible, and not need to speak to a staff member unless necessary.
You also need to consider how you can reset passwords and solve other account issues, either by using other API endpoints to handle these tasks or via an API account page.
Stick to standards
No matter which API protocol or architecture an API uses, they all have standards or styles they should follow. Some are more strict than others but rarely does anything break if they don’t follow them. Developers often expect APIs to follow certain patterns, and contradicting those expectations can cause a bad developer experience.
For example gRPC-based APIs are expected to use protocol buffers to define data structures, and while GraphQL is more of a query language for API data, GraphQL clients consuming that data also expect a certain structure.
For example, consider a REST-based API. REST is not a standard, which has led to many APIs describing themselves as RESTful or an “HTTP API,” which doesn’t do much to help you weigh up options. However, HTTP is a standard, so assessing if an HTTP or REST API uses the appropriate methods for operations can help you evaluate the design of an API. For example, the following HTTP methods should match the intended action. These match the create, read, update, and delete (CRUD) operations typical with accessing data in storage.
- GET: retrieve data
- POST: add new data
- PUT: update existing data
- PATCH: update a subset of existing data
- DELETE: remove data
You can also assess if an API uses resource names and nouns that make sense. For example, if an API manages invoices, then it might make sense for the resource name to be /invoices, followed by a resource ID, and then any other relevant sub-resources, such as /pay to pay an invoice.
REST does not define any format for a response body but look for those that use something structured that applications can parse, typically XML or JSON. The output should be well-formed, using useful keys and values, and the most appropriate structure for collections of data. Think of all that time you have wasted delving into a JSON data structure trying to figure out how to access the data you’re looking for.
Similarly, HTTP does provide a suite of status codes to communicate the outcome to users and clients, and a good API should use (and build upon) those rather than create its own error codes. This is a minimum to help you debug the API as you build your applications around it. It’s even better if it provides helpful error messages and debug information.
Designed around use cases
A good API should reflect common uses for it, not the architecture of the underlying code. If users frequently need to bulk pay invoices, an API should exist that lets them do so, not force them to jump through a series of other endpoints to accomplish the task.
2. Experience before business
Friendly plans and limits
API vendors generally fall into two camps for charging users: those who charge per call and those with plans that include a certain amount of calls.
For the former, make sure you research what constitutes an API call and how many you need to achieve certain tasks important to your use case. An API that costs more per call but lets you accomplish more with one call could be more cost-effective than a cheaper API, but you need multiple calls to achieve the same.
You need to make the same calculation for the latter option, but also check what happens if you go over that limit (typically for a month), are you charged excess fees, or is your access terminated with little warning?
Offer more
An API using a known architecture and following standardized patterns is essential but even better if a potential provider offers pre-built SDKs to match the programming language you use, making integrating the service easier with your application. Be wary of API documentation that autogenerates “SDK” code that may not suit your programming language setup.
3. Support
Communication
An API is a crucial component of many businesses, and we have all witnessed applications or services failing due to an external resource’s downtime. While choosing a provider with low downtime in the first place is ideal, it will happen, so when it does, you want to know that your provider will keep you informed, and most crucially, learn from past mistakes.
Responsive
Hopefully, you rarely need help with technical, account, or payment issues, but if you do, what options are available for you to do so? How much do you have to pay to get the kind of support responsiveness you need? It’s especially worth noting what options are available in your time zone.
Responsible
If functioning and reliable APIs are essential to your business, it’s worth checking what the service level agreements (SLAs) for a service are, and what happens if they are not met. Check how the provider handles versioning and changes to APIs. Do they suddenly make endpoints depreciated, potentially breaking your applications, or do they have long periods of depreciation allowing you to transition between changes.
Informative
While a customer portal isn’t an essential part of an API, it’s a “nice to have” that can help everyone from developers to administrators and accounting teams see the status of a service you pay for and manage certain administrative tasks. There may be endpoints that provide some of the data for ingestion into your own dashboards if there is no web-based portal available.
If the API is an interface to data, you should be able to manage and export that data if you want to switch providers. Under certain jurisdictions, there are probably regulations (GDPR and CCPA, for example) that enforce this, but this doesn’t mean a provider follows them, and this may be an important factor for you.
