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
Explore other sections in this guide:
There are some general principles that should be used during API development. The first thing to consider is that application programming interfaces are used by programmers. "That means that API design is not just about structured software design, but also about human understanding," said Peter Hendriks, IT architect and Competence Center Java lead at Netherlands-based Info Support.
API design is not just about structured software design, but also about human understanding.
IT architect and competence center Java lead, Info Support
A good API supports a limited set of well-defined use cases or scenarios. Start out with creating example code that uses the API for all these scenarios, Hendriks said. He explained that example code is the best way to get feedback on usability, and the code can later be used for tests and documentation. If example code is "really good," users will copy-paste or emulate examples closely. That's the "art" of API development, he said.
Hendriks uses a usability model by professor Ben Shneiderman for assessing API usability. Shneiderman is the author of the book, Leonardo's Laptop: Human Needs and the New Computing Technologies. For Hendriks, the key elements of the usability model include:
- Learnability: How easy is it to accomplish basic tasks the first time?
- Efficiency: Once users learned the design, how quickly can they perform tasks?
- Memorability: When users return after a while, how easily can they re-establish proficiency?
- Errors: How many errors do programmers make, how severe are these errors, and how easily can they recover from the errors?
- Satisfaction: How pleasant is it to use the design?
On the science side of API development, a variety of tools are available to help. For example, static analysis tools, such as FindBugs for Java code, can do a great job at detecting problematic API design and bad API usage. Hendriks frequently uses JSR 305: Annotations for Software Defect Detection, a standardized library that provides simple annotations to declare basic API hints, such as optional nullable values or support for multithreading. "FindBugs can detect many problems based on these annotations; not just in API design or implementation, but also in API consumer code," Hendriks said. He finds FindBugs easy to use and helpful for preventing a lot of common mistakes.
Many code-quality tools, such as SonarQube, also provide statistics that apply to API quality. "The LCOM4 statistic, for instance, implies that a class may be divided into multiple classes," Hendriks said. Furthermore, he noted, basic limits on lines of code per class and limits on the number of parameters per method also keep API complexity down.
Readers, does your organization use these API development best practices and tools? If so, what are their pros and cons? If not, share your team's methods and tool experiences in the comments section, so our experts can offer advice tailored to your needs.
About the author:
Alan Earls is a Boston-area freelance writer focused on business and technology, particularly data storage.