Even as reliance on APIs continues to grow and become a part of the lifeblood of enterprise systems and startups alike, most developers have been building and using APIs for years, even decades. As such, there are certain practices that have become commonplace among the developer community over time. Many API trends, like using JSON and relying on OAuth 2.0, have become de facto standards for API providers. However, when we look closer at the methods of some key players in the API space, what you thought you knew about API best practices is debunked.
From left to right: Neil Mansilla (Runscope), Erik Michaels-Ober (SoundCloud), Leah Culver (DropBox), Wynn Netherland (GitHub), Jim Heising (IFTTT)
At South by Southwest Interactive (SXSWi) last week in Austin, amid the hundreds of sessions spanning industries, we were able to bring together some of the leaders in the API technology space to reveal their beliefs about five common API trends. Moderated by Runscope’s Head of Developer Relations Neil Mansilla, the Secrets to Powerful APIs panel included Erik Michaels-Ober of SoundCloud, Leah Culver of Dropbox, Wynn Netherland of GitHub and Jim Heising of IFTTT. All of these companies have relatively small API teams ranging from one to eight engineers, but their APIs are among the most popular APIs in the country. While the panel wasn’t recorded, we’re revealing the most notable insights below.
Three API Trends, Debunked
Dogfooding
Many companies tout the value of actively using the same API that they offer to customers and partners internally, including Dropbox, GitHub and IFTTT. This practice allows companies to understand first-hand how their consumers experience the API, and thus follow a proactive approach to ensuring their API is performing optimally. However, SoundCloud adamantly takes the opposite approach, and has recently moved away from a one-size-fits-all (OSFA) API to microservices architecture following the model Netflix put forth with its API redesign.
Michaels-Ober explains that the OSFA API approach makes the API the single point of failure, but having separate API servers allows SoundCloud to deliver higher availability and contain issues. Furthermore, a public API should be generic, since it needs to support many unknown clients, while customized APIs can focus on the needs of a single client, so the data can be highly customized when it doesn’t make sense to do so in a generic API. Michaels-Ober adds that SoundCloud developed a backend-for-frontends (BFF) layer that allows its teams to easily generate client-specific servers. These changes to its infrastructure have allowed SoundCloud to ultimately increase independent speed of delivery. Individual teams can add features without the dependency of waiting on the public API team to ship it.
Schemas, documentation and client libraries
Making the move to microservices requires new ways of thinking for ensuring that consistent information is being shared across teams that are using a lot of APIs, which has driven the widespread adoption of a host of API definition and documentation tools among the developer community. Despite their popularity, none of the panelists uses any of the contemporary schema definitions like Swagger or RAML, and their documentation isn’t bound to any code or framework. By hand-rolling their definitions and documentation, these companies have the utmost control in how their API is structured and its representation of their company and brand.
In a similar vein, the panelists discussed the necessity of maintaining client libraries, and responses differed slightly, though the overall consensus, as Michaels-Ober explains, is that as an API provider, the focus should be on offering a solid REST API that’s easy to consume instead of spending resources developing libraries for any and all possible client scenarios. With new languages coming out weekly, maintaining individual client libraries becomes less and less scalable. Culver adds that Dropbox has a well supported SDK for the more popular languages like Python, but the team doesn’t have the means or need to have such solid SDKs for all languages. However, Netherland notes that GitHub has a variety of client libraries that are well maintained, which can be helpful for getting developers up and running quickly in opportunities like hackathons. The common thread among all panelists is that whether they support one or several, all of their client libraries are hand-rolled, keeping the control with the API provider and ensuring the high quality libraries that developers desire.
Security and authorization
As opportunities to share and store your data in the cloud grow, security becomes a chief concern among enterprises, and developers need effective tools that meet industry standards, but are also easy to use. GitHub supports basic authorization, and all panelists’ platforms support OAuth 2.0, which is a requirement for all but SoundCloud. However, they were quick to cite deficiencies in the specification and opportunity for future improvements. Culver, who is also a co-author of the original OAuth 1.0 specification, points out that when OAuth was created, smartphones did not exist. Therefore, one of the biggest concerns among panelists is the lack of innovation in authentication for mobile. Culver notes that a solution that is secure enough for end-users and useful enough for developers does not exist yet.
Another issue panelists noted with OAuth 2.0 is that scoping can be unwieldy. As a business, offering and/or platform grows, defining new scopes becomes increasingly difficult. Heising explains that implementing scopes is particularly arduous at IFTTT, as multiple triggers are tied to one request. If he wants to add a trigger in the future without reactivating a previous trigger, adding a new scope with new permissions is tricky. He adds that OAuth was built around a visual interaction that takes place when an app is in use, however, it doesn’t take into account future scenarios, so the current solution is another all or nothing approach. Culver continues that for Dropbox, an all or nothing approach to security would be detrimental to the user base. So scoping, while time- and resource-intrusive, is essential.
While many of the practices these panelists follow are counter to common belief, mostly because they require more time and care from the API provider, the results are clear. Healthy and well-maintained APIs are essential as consumers rely on multiple apps on numerous devices. These APIs are highly sought-after and widely consumed, and fruits of their efforts can be seen in a booming developer community and growing base of satisfied end-users.