Mike Amundsen, Principal API Architect at Layer 7 and author of "Building Hypermedia APIs with HTML5 & Node" recently embarked on a global tour, presenting a series of API design workshops in Chicago, Sydney, Melbourne and Toronto. InfoQ attended his workshop in Melbourne on July 25th.
Amundsen's design tips focus on the USE paradigm which is an acronym for Usable, Scalable and Evolvable. Along the way, Amundsen describes three common "styles" of API implementation along with their benefits and limitations with respect to USE. Versioning is discussed at length with Amundsen advising to "never use versioning, ever - unless you have to." Favour evolvability instead.
"Usability is the ease of use and learnability of a human-made object" quotes Amundsen, reminding us that APIs are literally your "Interface" and should focus on users and tasks. "Be prepared for empirical measurement and to iterate on your interface design," says Amundsen.
"Scalability is the ability of a system to handle a growing amount of work in a capable manner." Understand the difference between scale-up and scale-out, says Amundsen. Scaling-up is easy in the short-term, but not sustainable. Scaling-out is hard in the short-term but more reliable over time. Amundsen advises using DevOps practices to support scale-out.
"Evolvability is the capacity of a system for adaptive evolution." Amundsen favors extending APIs over versioning whenever possible. "Don't version unless you absolutely must, and it is rare that you absolutely must." Versioning makes sense for internal code management, but web API users only care if something breaks. Change can be accomplished without breaking by "never taking stuff away." Extending an interface means never change the meaning of the existing data structures and make all new additions optional. However, sometimes you have to break things and that is when to use versioning. In that case, make versions easy to identify. "Make it easy to build, make it easy to test and make it hard to cross the streams" says Amundsen. "But be ready for clients to ignore all this, because they will." Amundsen advises to put version identifiers in the URL. Don't put them in the header or in the payload because that makes them easy to ignore.
Amundsen presents an overview of the three most common styles of API implementation: Tunnel style (SOAP), URI style (CRUD) and Hypermedia style (REST), with a review of their history, strengths and weaknesses. Amundsen emphasises that these are "styles" not standards.
The Tunnel style uses SOAP to relay messages in a transport-independent manner. With a focus on functions and methods this style has good "usability" characteristics. There is good tool support and strong governance mechanisms for the enterprise. However, limitations include stack dependencies that lead to an "all or nothing" lock-in, poor support for HTTP and decreasing popularity among programmers. In terms of evolvability, SOAP creates big governance and versioning problems because even small schema changes can be "breaking changes". Amundsen notes that many people have departed from the SOAP proxy model to use SOAP more as a messaging model which avoids some of these drawbacks.
The URI style is the familiar use of HTTP verbs and (usually) JSON data structures to manipulate web resources. Amundsen reminds us this style is not REST with a reference to Roy Fielding's 2008 blog post asserting that APIs are not REST if they aren't hypertext driven. URI style is an object/entity-oriented style used by the vast majority of public APIs today. HTTP is well-known, object tooling is good and "hacking" on such APIs is relatively easy. However usability is hampered because the HTTP method set is small and URI modeling is not standard. Users must map domain methods to resources and HTTP methods. The URI style is "very easy to start, but becomes hard to scale and evolve" says Amundsen.
The final style that Amundsen describes is the Hypermedia style, or REST. Usability is enhanced over the URI style by the inclusion of media types and link relations which Amundsen says are "crucial for shared understanding." The Hypermedia style exposes tasks and use-cases and "is getting closer to what SOAP was doing in providing a machine readable way for documenting workflow." Hypermedia favours evolvability and leads to services that are useful over long periods of time. But the style is regarded as esoteric and there is poor tooling available. Amundsen refers to Siren as an interesting hypermedia framework to watch.
Amundsen is a frequent contributor to InfoQ. His new book, "RESTful Web APIs" co-authored with Leonard Richardson and Sam Ruby is due out in September.