This article is part of an Essential Guide, our editor-selected collection of our best articles, videos and other content on this topic. Explore more in this guide:
1. - API management: What you need to know: Read more in this section
- Respect the servlet API for effective portlet development
- Want API success? Devise a third-party developer community
- API project planning: Steps to add value in data, app integration
- How to build an application program interface
- API best practices, problems and advice
- API design requires key principles, artistic thinking
Explore other sections in this guide:
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.
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
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."
For consumers, a bad API means a longer development cycle and a higher defect rate.
IT architect/Java lead at Infosupport
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.
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.
- 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."
- 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."
- 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.
More on API development
API a touchdown with NFL stats company
API management enables gift card strategy
Guide to application programming interfaces
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.