The Long-Term Ramifications of Poor API Design Posted in Design Tyler Charboneau April 21, 2020 Our digital landscape is dominated by services, many of which power the daily experiences we rely upon. Banking, entertainment, and numerous other industries deliver core functionality to their customers through their APIs. What happens when design practices are lackluster? The Instant Gratification Trap API design and deployment are tied closely together—for better or worse. There’s a real business advantage to introducing your APIs first. Customers can integrate your services before even consulting competitors. This potential short-term gain is attractive. We can discuss the ideological war between engineering and marketing, but that may be best reserved for another time (or perhaps a group therapy session). Chasing instant gratification is understandable, but dangerous. It’s like developing a tentpole API when your core services really require thick rebar. Ideally, the design process would include thorough stress testing and optimization. Reliability is also crucial. Rushing an API design into production could result in a few things: Increasing long-term costs—and losses—for you and your customers Unexpected downtime Lackluster scalability and poor security A lack of consistency, which can hurt the developer experience Vendors must realize that being first isn’t necessarily best. Any design shortcomings become amplified as user bases grow. This can cause technological chaos. We want to catch errors in development—not production—so they’re both easier and cheaper to fix. If we really want to discuss cost, major API issues can drive customers away from your solutions. You don’t want disgruntled and prospective users flocking to other APIs. Winning users back is one challenging task. That can be extremely frustrating for a company. It could even make developers decide that API creation isn’t worthwhile, which can harm the organization down the road. Mounting Costs We referenced how user flight can impact your bottom line. The resources required to patch major issues can be immense. Issue resolution is cheaper earlier on in the design process. Considering that many companies pushing new APIs are startups, these unforeseen costs can lead to collapse. These consequences can be acute. However, designing an API that will clearly need upgrades to remain functional (or maintain feature parity with competitors) is a recipe for expense. Agile organizations lacking formal QC procedures may ship APIs before they’re production ready. Customers en masse have a knack for uncovering critical issues not found in alpha. The privacy status of your API will influence how much exposure each issue receives. Take for example Amazon’s 2013 outage, which lost the company $4.8 million in 40 minutes. Your API design can directly impact your profitability and that of your customers. API issues lead to accumulation of “technical debt,” or measurable costs associated with expected future maintenance. That can leave teams scrambling for fixes—requiring multiple man hours. If you contract any portion of your API to third parties, those rates add up quickly. Building software around a substandard API can be also expensive. Your users may also require added support. Exasperation via Downtime What if we encounter a crippling issue? This can interrupt key services. API flaws can cause downtime—a period where users cannot access essential features. First and third-party adoption can exacerbate this issue. We’ve seen these problems arise periodically with Reddit—a platform boasting over 330 million active monthly users. The social giant receives a whopping 14 billion monthly screen views. Interestingly, 70% of the site’s video views occur on mobile devices. Why does this all matter? That traffic is immense! Reddit is the third most popular website in the United States alone. It’s a unique platform where third-party development has blossomed. The company provides external developers with APIs which unlock content access throughout their apps. These mobile apps garner a massive amount of traffic. Video (and image) consumption puts the core Reddit API through its paces. When this API experiences problems, millions are denied access to the content they adore. Even the best designed APIs suffer from occasional outages. Imagine the potential pitfalls with a substandard API. That downtime causes a ripple effect across the ecosystem. Users grow frustrated. Reddit catches heat, and third-party developers shoulder blame when the situation is out of their hands. Third-party Reddit developers are a captive audience, since Reddit monopolizes access to its content. There are no backup APIs to harness. Depending on the severity of the issue, this resolution process can be lengthy. Designing for User Growth We can apply these lessons to any app, especially when APIs aren’t designed effectively. APIs must be stress tested to handle traffic spikes. Consider that popular platforms become marketing engines as they grow. Service interruptions for apps like Reddit and Instagram can impact those who leverage them for promotion—at both the corporate and grassroots levels. This can lead to revenue loss. Enter our next design element: scalability. Many companies design APIs knowing they’ll gain modest, niche followings. Perhaps your API has mass-market appeal. Its design must be rock solid and ready to scale alongside your user base. It must handle thousands or even millions of calls in a given period—returning valid results without high incidence of errors. You don’t want applications to crash and become victims of their own success. Your API must be scalable, durable, and reliable. This will keep your users and customers happy, allowing you to tackle additional projects. Security Erodes as Visibility Increases “Macs don’t get viruses.” This single phrase had (some) merit at one point, but came with a caveat: the Mac platform lagged greatly behind Windows in popularity. That low visibility drove attackers to the Windows platform instead—hence why most malware and viruses hampered PCs. That perception created a false sense of security, which has proven problematic as Macs have gained market share. Granted, we’re discussing operating systems, but similar lessons apply to our APIs. Haphazard design often shirks on the fundamentals. Companies may shelve security concerns or unknowingly create vulnerabilities due to bad practices. Follow guidelines like these instead: Use tokens for device and user identification Encrypt your APIs and require signatures Find security holes early Use quotas and pagination limits to control traffic flow Consider using an API gateway for control and analysis We use these APIs for many things: data access, authentication, content dissemination, and more. Glaring security holes can place sensitive information at risk. Attackers can access private data or disrupt key services. This can erode trust in your API while introducing new costs. It’s crucial to design according to best practices to prevent such problems from arising. The growing popularity of your APIs will heighten the visibility of exploits—attracting nefarious actors. Both REST and SOAP APIs benefit from fortification, even at the most fundamental level. Designing with Foresight is Key We get it. You have an awesome service or feature you’re raring to introduce to your users. The allure of fast-tracking development is powerful, but it shouldn’t trump sound design. Always remember that careful API will secure its relevance in the present and future. Its profitability, uptime, scalability, and security stand to benefit. We don’t want to use excessive boilerplate as a crutch, or cast aside best practices for superficial gain. Avoiding nasty long-term consequences will help your projects flourish.