|
New eBook on Web API Design
Versioning Tips for RESTful API Design
Brian Mulloy at Apigee wrote a short article on versioning for Web APIs where he contrasts three different methods of including versioning information in a URL. These include using a timestamp or version number in the URL path, or accepting a version number as an optional parameter. Brian suggests using a mandatory version number as far left in the URL as possible, and using a whole number instead of dot notation for your versions. APIs Are For Human Beings
API Design Anti-Patterns
Open APIs: State of the Market
John Musser gave a presentation at Cloudstock during Dec 2010 about the state of open APIs for the Web. He starts with the big picture, covering why you may want to create an API and the surge in new Web-based APIs that have appeared over the past few years. He then goes into the business of APIs, looking at various business models and scalability needs of successful APIs. The focus then turns to design and technology issues, such as protocols, data formats, styles, and authentication. RESTful API Design
Brian starts off with a poor unstructured Web API and evolves this toward a better design. He suggests that you should avoid verbs in your URLs and that you only need 2 base URLs per collection: one to access the collection and one to access a specific element. He follows the advice in the Wikipedia article on RESTful design that POST queries are used for creation, GET for reading, PUT for updating, and DELETE to remove. He also covers topics such as good ways to support pagination of results, specifying the response format, and versioning of your web service. This is a great overview of good Web API design, and it’s only 16 minutes long. Check it out: API Design Interview Feedback
Under the topic of great API design, Ivanka provides various quotes from her interviews that support the qualities of consistency, predictability, and learnability, as well as noting that a good API is easily extended and gets better over time. In terms of API documentation, she states that there should be an overview to explain what the API does, that documentation should be concise and logical, use navigation to expose content, and offer tutorials to help developers starting from scratch. Jenkov’s API Design Tutorial
Version Aversion
Top 10 API Pitfalls
Preserving Backward Compatibility
Garrett Rooney wrote an article called “Preserving Backward Compatibility” where he talked about how backward and forward compatibility is maintained for Subversion, client/server source control management (SCM) system. Garrett talks about the importance of planning ahead, not throwing anything away, and of hiding the details. He also talks about exposing and hiding the dependencies of your API. This is a great article to read about how backward compatibility is maintained in a complex real-world system. API Design Matters
Some comments on this article can be found here. Symbian’s API Change Control Process
The Symbian Developer wiki defines a process for public API changes to the Symbian platform. This involves a submitting a Change Request (CR) to an Architecture Council for approval before code is integrated. The main principles of their API development process are:
For details, see: The API process is illustrated with the following figure:
KDE’s Binary Compatibility Policy
The KDE Project offers some guidance on the difference between source and binary compatibility, and provides a great list of Do’s and Don’ts if you want to maintain binary compatibility for an API. This document defines binary and source compatibility as:
|
The book is accompanied by a source code package that contains many of
the examples in the text.
Download it for free.
Dr. Reddy has also published a computer graphics book called Level of
Detail for 3D Graphics.
Check it out too!.
The folk at apigee have distilled everything they’ve learned about Web API design over the last few years into a new free eBook called “Web API Design: Crafting Interfaces that Developers Love.” This collates many of the details from their various blog posts into a single reference, covering topics such as REST, handling errors, versioning, authentication, complementary SDKs, and many others. If you’re writing a Web API for your platform this is a great read.
In this Twilio Engineering blog article, Frank Stratton makes the point that computers don’t care about API design. APIs should be designed for human beings first and computers second. Using example Web APIs developed at Twilio, he talks about the need for having many eyes and minds see the design first, simplifying the surface area of your API, and how it is easy to add new calls but hard to remove existing ones.
Google’s Alex Martelli gave a speech at PyCon 2011 focusing on API anti-patterns, which he defines as counterproductive behaviors that are often systematically repeated. He states that the worst anti-pattern is not having any API at all, and the second worst is not having any design (an accidental API). Most of the talk is aimed at a process or design level, though a couple of specific code examples are given. For example, Martelli talks about the fact that a lot of software is overdesigned, but when you’re dealing with an API it’s actually good to spend a lot of up-front time thinking about future expansion and evolution before release. In terms of designing a good API he suggests thinking about 3 ways to implement your API: the common concepts will be the core functionality that should be in your API. He also suggests that you should use your own API as much as possible. Finally, he spends some time talking about choosing to do something one way, not two ways, i.e., taking a stand and making a decision. The talk is just over 40 mins and offers some great high-level insights into how to go about designing a good API, be it C++, Python, or Web-based.
Brian Mulloy recently gave a presentation about Web API design at Saleforce’s Cloudstock event in San Francisco. He has provided a video of his talk that is well worth checking out if you’re interested in RESTful API development for web services.
Ivanka Majic conducted several interviews with developers about what makes a good API. The three basic categories that she came up with as a result are that an API should be designed well, should have good documentation, and good support.
Jakob Jenkov has compiled an extensive collection of tutorials on how to design good APIs. Jenkov summarizes the qualities of a sound API with the statement: “Solve my problem, with minimal effort from me, and don’t get in my way.” His tutorial is broken down into several sections, including: Lots of Upfront Design, Keep it Small and Focused, Don’t Expose More than Necessary, Sensible Defaults, Optional Abstractions, Central Point of Access, among others. His tutorial covers a lot of ground and offers a lot of valuable tips, including several code examples in Java to illustrate his points.
The Communications of the ACM published an article called “Version Aversion”, which discusses various approaches to using version numbers in a software project. Much of the discussion mirrors the content in my book, API Design for C++, including the use of major/minor/patch version triples, tips on when to bump each of these version numbers, and reference to more esoteric versioning schemes like the Windows operating system choice of Windows 95, Windows 98, Windows ME, Windows NT, Windows XP, etc. You’ll need access to the ACM Digital Library to read the article.
Rick Nucci wrote this article exposing 10 of the most common API pitfalls that he has encountered in Web services code (also known as Software as a Service, or Saas). His list includes problems such as exposing operations instead of objects, constantly changing the API on your users, not thinking about performance issues such as throttling services, and getting caught without a strategy for your API.
Michi Henning wrote an article in ACM Queue called “API Design Matters” in which he suggests that changing APIs should be a criminal offense and that authors of poor APIs should be held accountable for their crimes. He notes that good APIs are hard to design and he presents some examples network and synchronization APIs that could be improved. He also calls for APIs to be documented before they are implemented.