It’s a very easy thing to say that if an API exists, then it’s useful. After all, if a developer creates an API, they must have created it for some purpose. However, what is functional isn’t always useful, and conversely, what is useful isn’t always functional. True success requires both facets.

In this article, we’re going to tackle the idea of what makes an API useful and functional, and why it matters. We’ll dive into a real-world example, demonstrate some hypothetical applications, and even set out a rubric by which your current or future API can be critiqued against — and possibly improved — with the end goal being to help developers discover their API’s core value.

A Matter of Terminology

The number of APIs in the wild is simply staggering — whether we’re talking about APIs that power smart cities or APIs that deliver something as simple as voice mail, current offerings are as diverse as they are numerous. With such a wide range of systems, discussing the objective qualities of functional versus good is quite difficult.

Because of the nature of subjective and objective critiques of such an extreme range of systems and services, terms undoubtedly get confused, conflated, or changed; what one user might find helpful, another might find useless, and vice versa. In order to properly consider an API on an objective, rather than subjective, basis, we need to set a few basic definitions.

Defining Functional

When we discuss a functional API, what do we really mean? Any API that delivers a call as requested could be defined as functional. Objectively, functionality can be defined as delivering data when requested in a usable format.

However, when designing an API, all the functions in the world will be absolutely worthless unless they are delivered in a way that is usable. Think about it this way — say you are invited to dinner at a friend’s house, and you aren’t sure how to get to their house. You ask them for directions. They proceed to give you directions citing such noticeable landmarks as “that weird green sign” and “that really good taco stand that I went to with Mark — oh, you don’t know Mark, do you?”

In this social situation, you’ve received a good amount of data, but that data is not functional — at least not by your standards. No street has ever been named after “that weird green sign”. The same could be said about an API — if an API delivers data as requested, but in a way that is non-standardized or unusable by the requesting system, it isn’t truly functional.

The takeaway? Functional systems are operational as designed, and are usable by the requested system.

Defining Useful

If functional is a subjective term, then discussing a term such as “useful” is really opening a can of worms. Anything can be useful in a subjective sense — an entire infomercial cottage industry has sprung up around creating tools to solve problems few of us truly ever have. Usefulness in the colloquial sense is almost always better defined as “useful to me”, rather than “useful by design”.

Useful in an objective manner, however, is far more specific than any personal definition of usefulness. When discussing whether an API is useful or not, what are we discussing? Certainly not the functionality — that has already been handled by our discussion on the term “functional” above.

Some things in life are easier to find when you’re looking for what they aren’t. Astronomers map black holes not by looking directly for physical manifestations, but for the absence of space around a black hole. Painters create not only with acrylic and oil, but with “negative space”, or areas of canvas without solid coloring. Musicians are fond of changing dynamics, accenting loud pieces with sudden silence.

When considering what “useful” is in an objective sense, we can also use this same technique to identify what “useful” is not. A useful API is not one that is confusing. Long, difficult to remember function names, parameters that don’t make sense, and poor documentation does not relate to functionality — the inability of the person performing the call to remember long names is not an issue of functionality, but of user experience.

Likewise, a useful API is not one that is designed for the moment. Systems evolve, and anything that does not have the capacity to evolve might as well not exist in the technical world. Designing an API to serve a narrow function, without scaling and extensibility, makes for a bad API, and creates a stagnant business environment.

In this way, “useful” has to do a lot with the user and developer experience rather than the system functionality.

The takeaway? Useful systems are only as complex as they need to be, and scale well through implementations and iterations.

Why it Matters

Why does this all matter? If your API delivers the functionality intended, isn’t it functional? And if the API has a relatively well-designed API experience and delivers the data as requested, isn’t it useful?

One of the biggest pitfalls a developer or business can ever make is considering their product or service from the narrow view of their personal experience. The CEO, Marketing Manager, and tech support team are not the only people who will be using your product, service, or system — there’s an entire world out there moving faster than we can even comprehend, and one misstep could mean the difference between success and failure.

This sort of “single channel” thinking is exactly what causes conflation of terms when considering functional and useful APIs — in the best case scenario, your user is going to utilize your API every single day in an infinite variety of opaque and transparent ways, and their experience will reflect upon your business; because of this, the design, nature, and quality of the API means everything. Additionally, your businesses and system will grow organically as your customer uses your API for more and more things — if your system is poorly designed, this will not occur, leading to stagnation.

Real-Life Failure

All of this redefining of terms and conflation of concepts is easily done away with, however, when we look at real-world case of failure. On November 14th, 2014, Netflix officially closed down its Public API. This didn’t come as a great surprise to many developers who utilized the API, as it had been closed to new developers almost two years prior, with rumblings and rumors of its imminent complete shutdown emanating thereafter.

The API was used in services such as CanIStreamIt?, a service that reported whether a title was available to stream on a variety of services, and A Better Queue, which suggested new movies based on previous titles using an advanced algorithm. Given this, why was it shut down, and why is it considered the paradigm of a non-“useful” and non-”functional” API?

The API was plagued with issues. Sweeping changes to functions and requests often came with little warning, breaking functionality for users of third party services. Documentation was incomplete, general, and scattered amongst various forums and documents. The Public API was actually two separate APIs functioning as one, with neither set providing complete functionality.

The development of the Public API was too privatized, a cardinal sin of API Development, without any communication between the developers of the API and the developers who utilized it. API keys would often expire without warning, leading to site breaking functionality issues for many developers. These issues, and more, caused developers to lose interest, causing lack of innovation; it can be argued that this was a cycle of negativity, with the Public API lacking support due to the lack of third party innovation, which in turn was caused by a lack of Public API support.

Ultimately, though the API operated just fine and delivered a sufficient-enough experience for users — it just wasn’t “useful” or “functional” according to our definitions. The API was never given the support it needed to take off, and was shut down as a result of lacking implementation and innovation. In the same year that Netflix was given Occulus Rift support through an official hacking event utilizing their private API system, it’s public API was retired.

A Rubric for Success

Given that we have taken our subjective terminology and created an objective metric by which we can judge an API, let’s take everything we’ve learned and apply it into a general rubric.

In order to be both functional and useful, and API must exhibit five basic qualities:

• Good Documentation: Documentation can make or break your system. As your API grows in capability, so too does it grow in complexity, and even the most powerful system in the world is completely worthless if nobody knows how to operate it. Example: “getResults returns survey results from server”.
• Simple Functions and Calls: Even if you do document your API effectively, a great deal of danger sits in what you are documenting. Are the functions and calls easy to remember? Do their names make sense? Is what they do implied in their names, leading to a better intiial understanding? Making sure your system makes sense is just as important as making sure others understand it. Example: “UserID” instead of “UserIDBooleanCustom”
• Usable Format of Data: Data must be usable — if it’s not, it’s just a nice collection of numbers and symbols. Organizing the data in a way that can be tied into other systems not only makes your API more powerful, it makes it extremely extensible. Example: “UserID=555” instead of “auth001991887_sheet8881993_resourcerequestsid=12399nn18373_userid_customvalue=charlie_userIDvalueset_userIDvalue=555”
• Future Proofed Scalability: Consider your API’s architecture, and choose an appropriate option. Failing to choose an architecture that supports the type of requests you wish to call, as well as requests you might consider implementing in the future, leads to a “band-aid” style API meant to solve your current problem, all the while creating new problems down the line. Example: If you’re dealing with a large amount of slow-processing data but need to implement features down the line that require high security, use SOAP rather than REST.
• Appropriate Project Planning: Keep it simple! When developing your API, there’s no reason to segment the development into subprojects, sub-APIs, development teams, etc., as doing so can cause crosstalk between teams, failure to deliver cohesive products, and confusion amongst your user base. Example: develop a single public API rather than multiple derivations of an API (unless specifically warranted).

By implementing these five basic qualities and considering the values shown throughout this article, you can not only ensure that your API is functional and useful, but that its implementation, public perception, and usability are as great as they can possibly be.

Conclusion

Much in the world is subjective — art, fashion, entertainment, it’s all relative to your personal choices and proclivities. As technology progresses, however, and the world of APIs transform into powerhouses of activism, art, technology, and commerce, certain standards must be met. Long past are the days where an API might get a few hundred hits from a dedicated base of technical wizards — the average user requires far more documentation, information, and a much better user experience than ever before.

Following the few simple concepts outlined in this article and looking at your API design lifecycle as a journey rather than a burden can not only breed success — it can become a success in its own right.