"Building regular software is like building a house," said NetBeans initial architect Jaroslav Tulach at JavaOne 2014. To change something in a house, "you can just close the door, throw all the people out, reshuffle the walls, change the windows, put additional floors in." With a public API, however, the architect has to get it right the first time. And when it's in place, there's really no changing it, because too many clients are locked into it.
Right off the mark, an API has to be useful and "cool" enough to attract users' attention, said Tulach, who is Oracle's NetBeans platform architect. In practice, a new API has to quickly reduce users' time to market and lower their total cost of ownership, all while being easy and, he dared to say, fun to use. Most importantly, said Tulach, "API use should lead to beautiful code."
This demand for first-release perfection is a heavy burden for API designers, according to Tulach. He described the API architect's lot in life in this video, as well as a novel approach to API design planning, the most important characteristic of an API and mistakes commonly made in creating a public API.
Making news with an API
Tulach recommends starting API design at the end of the process by writing a press release about the results of the project. A press release describes the project team's success in meeting business and user requirements and can be the touchstone that keeps a project on track.
Most software development projects start with elicitation of some requirements and a rush to write code. "If you start development with code, you get buried in code and lose track of what you're trying to achieve," he said. This often leads to rework when new business goals and user needs turn up.
The press release kicks off the design planning process, during which critical policies are established. These include setting criteria for accepting patches, defining the API evolution story and developing an end-of-life policy. Regular release cycles should not be a part of the lifecycle plan for an API. Put all creativity and meticulous attention to detail into the first version. Any future changes should be minor.
A required blast from the past
When considering patch policies, documentation, testing and evolution practices must be established, but the most important capability is backward compatibility. Preserving investments is a must. "Retain previous code, and users will be satisfied," Tulach said.
API designers never know who is using their public API. "You can never completely refactor a public API," said Tulach. "It's like designing a universe where the API is like the fundamental laws of physics, and everything else depends on them. One little change and everything falls apart."
An API must be stable, Tulach said. Avoid visible refactorings. An API should be able to live a long time without changes.
The quest for the perfect first release is probably a new approach for most developers, Tulach said. There's a big difference between developing code and designing a public API.