Digging into quality: API best practices, problems and advice

Planning and testing are crucial parts of API development, because a bad API can mean a longer development cycle and a higher defect rate.

For many large services, an application program interface (API) has become the primary channel for reaching users. Services like SalesForce, NetFlix, Facebook and Twitter typically serve more requests through API calls than through their own front-ends for users. Considering many APIs carry such heavy burdens, it's surprising how many are rushed through development without adequate testing, according to IT architect Peter Hendriks and other API development experts.

API quality matters a lot, both for API consumers and implementers. "For consumers, a bad API means a longer development cycle and a higher defect rate; and in some cases, even a skills problem in the team -- a dependency on the one person that mastered the black art of calling the API correctly," said Hendriks, IT architect/competence center Java lead at Netherlands-based Infosupport. For API implementers, he said, API quality shows in the popularity of the API, as well as the volume of support calls or the amount of supporting documentation or training needed.

Fortunately, there are many approaches that yield better and more consistent results in API development. Those approaches include leveraging best practices at leading organizations, considering usability and deploying appropriate tools.

In the early days of the technology, APIs to manipulate Extensible Markup Language "were terrible," Hendriks said. Javascript Object Notation (JSON), an alternative data format, became popular very quickly, because APIs were very simple from day one. A similar situation exists with Spring versus Java Enterprise standards in the Java space, he noted. "Spring competed on API quality for the most part, causing radical API changes in the newer Java Enterprise standards in order to stay relevant," he said.

Les HazlewoodLes Hazlewood

A common mistake is publishing an API and then deciding it needs changes -- changes that might impact customers, according Les Hazlewood, CTO of San Mateo, California-based Stormpath Inc., a user management and authentication service for developers. "You want to be frugal when you release an API," he said. Make sure to learn about and follow all the best practices, even though an API is based just on an architectural style rather than a standard.

For guidance in constructing REST APIs at Stormpath, Hazlewood looked at what was being done by Twitter, as well as less well-known but robust business-oriented APIs. He found the work of Roy Fielding very valuable. Fielding's doctoral dissertation describes Representational State Transfer (REST) as a key architectural principle of the World Wide Web.

Digging into API quality

Peter HendriksPeter Hendriks

Hendriks explained that in modern application development, most application code involves calling an API. The code uses APIs provided by the platform, such as the Java APIs, frameworks (Java Enterprise Edition APIs, for example), third party libraries (like log4j for logging), or external systems and services (Web Services, Twitter, Facebook, SalesForce, Google). "API quality determines how easy it is to learn, how productively can be used and how likely it is that mistakes will be made," Hendriks said. And, he added, "For a developer, API quality can make a night-and-day difference in their effectiveness."

On top of that, the code that developers write is shaped by the APIs they use. "It is very difficult to write clean code once you need to consume a poorly designed API, but a beautiful API will almost automatically lead to nice API consumer code," Hendriks said.

For consumers, a bad API means a longer development cycle and a higher defect rate.
Peter HendriksIT architect/Java lead, Infosupport

According to Hendriks, libraries and frameworks dominate current application development. "Nobody builds anything from scratch anymore. It is much easier and more productive to use a good framework. This makes API design very important for application developers; virtually every code they write calls an API," Hendriks explained.

Since many capable frameworks are available nowadays, there is comparatively little competition for features. However, he added, the newest frameworks place heavy emphasis on API design. Their main competitive advantage is the ability to start fresh and fix design mistakes in established frameworks, making them easier and more productive to use, he said.

Hazlewood relies on three general principles that should be applied to creating a REST or JSON API.

  1. Be sure you thoroughly understand the HTTP protocol and how it handles posts and puts requests, because "HTTP is the foundation that REST is built upon."
  2. Understand how to link between resources and code. "The Internet is at its massive, global scale because of linking ... so linking and data types matter."
  3. Determine how you are going to represent a single resource as compared to a group of resources. Although there are no formal standards, developers should look for best practices.

What's on the horizon for API design? For the Java world, at least, support for lambda expressions in Java 8 is a "big thing" for API design, according to Hendriks, because it makes it much easier to pass behavior to an API. "Until Java 8, this required a lot of boilerplate code with confusing semantics. Many API scenarios, such as user interfaces, message handling or parallel programming will now be much easier and less error prone," he explained.

Additionally, in Java 8, many other small improvements are made to static code checking and annotation support. That means tools like FindBugs and JSR305 can be used in more areas of the API than was previously possible, Hendriks said.

About the author:
Alan Earls is a Boston-area freelance writer focused on business and technology, particularly data storage.

Follow us on Twitter @SearchSOA and like us on Facebook.

Next Steps

API a touchdown with NFL stats company

API management enables gift card strategy

Guide to application programming interfaces

Why API management features can be overwhelming for some.

Dig Deeper on API management