Why are APIs so hard to use? - Part 1
This series of articles talks about the difficulties of learning and using APIs. In Part 1, we cover general difficulties. In Part 2, the discussion centers around issues related to orthogonality. Part 3 will explore problems with the abstraction of data.
Why are APIs So Difficult to Learn and Use? An Application Programming Interface (API) comprises reusable functionality accessible through a remote call over the internet. In addition to accessing disparate data, APIs serve as a foundation for creating applications by saving programmers the time necessary to code multiple important functions from scratch.
In a textbook-perfect world, using APIs to build an application would be a simple three-step process:
- Gather requirements from clients and other stakeholders
- Map requirements to API components and functions
- Type in “glue code” to combine the APIs’ functionality into the required application
Unfortunately, real software development with APIs is not so simple, since programmers experience significant challenges when using APIs for many categories of functionality: networking, databases, web applications, web services, graphics, user interfaces, text processing, and so forth. Learning and using APIs can be difficult for reasons stemming from the very nature of software. For example, due to its high ductility, software can evolve quickly, which means that APIs can rapidly become outdated. In addition, software is intangible. Unlike physical machines, remote services cannot be “opened up” to reveal how it works, so when learning an API, programmers cannot call on many of their tactile-visual skills. Finally, software complexity not only results from inherent factors but also from a great variety of external factors: “Are the right credentials being used? What are the right parameters? Is this unofficial API documentation on a random web site trustworthy?”
Moreover, learning and using APIs can be difficult for reasons stemming from the culture around software. For example, there is incredible schedule pressure due to a desire to be first to market, so designers lack time for creating as much API documentation as might be desired. However, the users of the APIs are under similar pressure, so they are often unwilling to invest time in wandering through poorly tested and documented APIs. Thus, universal schedule pressure creates a tension: API designers can never supply as much documentation as users demand.
This article will focus on four specific challenges related to learning and using APIs. The discussion of each challenge includes an outline of strategies that API users employ for dealing with that challenge, as well as strategies that API designers utilize for helping their respective API users. Although most programmers learn these strategies over the course of many years, perhaps they could learn some of these strategies before they enter the “real world.”
Programmers get help from a variety of sources, each with particular strengths and weaknesses. Blog and whitepaper tutorials incorporate a gentle learning curve. Their weakness is their relative lack of searchability and completeness, and they may not exist for newer APIs.
“Googling for code” often proves helpful for open source APIs, since many developers have used these APIs and published their code on the web. If a set of API functions looks promising, but the proper sequence of calls is unclear, then it can be helpful to type function names into Google to retrieve examples where people have successfully navigated the API. The weakness is that code samples alone reveal little of the semantics behind functions.
Online API reference documentation like JavaDoc is ubiquitous. One weakness is that finding an up-to-date or totally complete document can take a long time. In addition, programmers can have a difficult time determining which functions are optional and which are required in order to achieve complex effects. Online interactive tutorials and sandboxes sometimes offer better searchability and power without sacrificing the gentle learning curve.
The final source of help is human contact through email, newsgroups, or direct verbal communication. This permits asking follow-up questions, and experts can tailor their instructions to a specific problem instance. The main weakness is that such people may have time to answer only a few questions by email each week.
In summary, although each piece of documentation gives some help, each piece also leaves some uncertainty about how to use an API. That is, documentation gives part of the picture, such as a list of available commands, yet it might leave other parts foggy, such as which commands are optional.
Strategies of API Consumers and Users
Although students and young developers might refer to only one source of documentation for an API, they eventually learn to seek several overlapping sources of documentation, which helps reveal subtleties in the API’s usage. Each piece of documentation can reduce the uncertainty of which API function to use, making the problem smaller.
In addition, experienced API users recognize when it is acceptable to use API functions whose semantics are only approximately understood. Not every application runs a pacemaker or a nuclear reactor. Sometimes it is better to write code that might contain a bug, and then fix the bug if it appears, than it is to try producing a perfect program. For example, if a script needs to initialize a new application’s database from a legacy system, then it is acceptable for the script to use somewhat imperfectly understood API functions, since the script only needs to run correctly once.
Strategies of API Publishers and Designers
API designers use a variety of strategies to facilitate those strategies by API users. For example, designers usually provide several forms of documentation so that users can employ the first strategy above. Perhaps the most powerful documentation strategy for API designers is to provide “Hello World” examples. The “Hello World” term originated in reference to examples of how to print “Hello, World!” to the console;
https://github.com/twitterdev/android-samples
This link contains the first such example for the Twitter Android SDK for the Twitter API. The term more generally can encompass any example that gives painstakingly precise instructions for how to accomplish one specific individual task using an API.
This sort of example includes the source code to meet a single requirement, making it utterly transparent which functions are required for one very simple API usage scenario; by implication, all other API functions are optional in the context of that scenario. The example also includes step-by-step instructions for building and executing the example.
A “Hello World” example leads the user directly to the code needed for one “API use case.” Of course, there are many such use cases, and the API designer probably cannot provide a “Hello World” for all of them — so in the worst case, the API user might still fall back on guessing games. Yet if the API designer writes “Hello World” examples for the most common API use cases, then in the average case, the API user may not need to guess much at all.
Finally, note that users must have an obvious, easy way to look up the version number of the installed API so that they can find the right documentation for their version of the API. Astonishingly, many so-called tutorials lack the most basic “Hello World” example, and some APIs even lack obvious version numbers.
This is why we created the BitScoop API integration platform. If you are an API Publisher, create a BitScoop API Map and publish it and an “Add to BitScoop” on your developer portal. API consumers using the BitScoop platform will not need documentation when using a BitScoop API map because integration, authorization, requests, modeling, and more are simply handled for you.
BitScoop API maps are the perfect place to implement flexible features for different use cases instead of in extra endpoints hard coded into the API. Create API maps for each use case you want to serve; such as a “Basic Social Sign In” map, or a “Media read-only Endpoints”. You can even create a basic “Hello World” API map that shows how to make a request to the most basic endpoint on your API.
These are only examples of what you can do with BitScoop API maps. Check out our current community supported API map list and see the possibilities of our new API paradigm. Users are only beginning to explore what is possible on BitScoop. Should you have any questions, don’t hesitate to reach out at https://bitscoop.com/support.
Continued in Part 2
