Amazon Web Services (AWS) remains the dominant cloud-computing platform in 2021 — single-handedly capturing 32% of the overall cloud market. That rise to prominence has been no accident.

AWS adoption and integration have relied upon the proliferation of APIs, which have unlocked access to the platform’s core features through the years. Accordingly, these APIs must be performant, secure, and enjoyable to use; otherwise, users won’t hop aboard. Luckily for AWS, this not-so-secret formula has been more or less perfected. It’s one reason why AWS processes over half a billion API calls per second.

Werner Vogels’ API Best Practices

Amazon.com VP and CTO Werner Vogels’ leadership has been pivotal in advancing AWS’ development strategy since 2006. Modernization, cloud transitions, and the microservices revolution have made API growth absolutely critical. That process hasn’t always been easy, according to Vogels. It has required plenty of experimentation and coordination between product teams. Additionally, internal standardization has helped unify AWS’ API designs platform-wide.

Considering that AWS has over 200 services under its umbrella, it’s easy to imagine how monumental the task of supporting them is. The opportunities for fragmentation and differentiation are huge. AWS and Vogels have poured consistent effort into refining their Crowd Control API: a standardized set of CRUDL APIs developed with behavioral consistency and streamlined management in mind. Users can thus do the following:

• Create, read, update, delete, and list cloud resources in a unified manner
• Access resources and services without coding specifically for multiple services
• Support earlier API versions on the development side while keeping newer services active in tandem
• Control both AWS and third-party services through Crowd Control’s control plane, boosting integration across platforms

This overall concept illustrates how AWS approaches its API design in many ways. You have legacy support, forward-thinking development, unification, and robust functionality without introducing superfluous complexity.

This approach fits Vogels’ interpretation of Gall’s Law, which states that all successful complex systems are built upon simpler foundations. In a nutshell, this exemplifies AWS’ 15-year evolution — its humble beginnings traced back to the launch of S3.

For example, Products like Crowd Control work because smaller components (the APIs) combine to do plenty of technological heavy lifting, shifting developmental burdens away from users. The same applies to individual services across Amazon’s portfolio too. Consequently, adoption skyrockets, and these APIs become the backbone of numerous projects across industries.

Werner expanded on these concepts and more during his keynote speech at AWS re:Invent 2021. How exactly does he view API development, and what key principles have emerged throughout his AWS tenure?

1. APIs are Forever

When a social media post graces the internet, it leaves a permanent impression on web users thereafter — that’s to say, it remains visible and “on the record” until the end of days. A similar thing happens with AWS’ APIs, though those outcomes are more intentional.

When AWS introduces an API, Vogels believes that this API must remain ever-present and largely unchanged. Once companies fundamentally change or remove a longstanding API from general availability, business customers who’ve built atop it will suffer. These breaking changes can interrupt daily operations and impact end-users. Pulling the rug out from underneath technical teams can undermine brand trust and loyalty.

There are both business and somewhat altruistic reasons behind preserving an API over time. However, what if you absolutely need to alter or develop your APIs to satisfy new frameworks and feature requests?

2. Never Break Backwards Compatibility

Many customers will want to leverage older API versions. Accordingly, calls from older API versions shouldn’t encounter problems. Leave the infrastructure in place to handle legacy versions. At worst, offer essential resources that ease upgrades or transitions to newer versions.

In fact, this philosophy mirrors those of other industry behemoths like Google. While Vogels and Amazon have made promises around their own APIs, Google’s own API Improvement Proposals documentation outlines best practices. Again, guidelines like these highlight just how crucial API longevity is to customer success.

3. Work Backwards from Customer Use Cases

Instead of letting engineers determine what an API should do, Vogels states that customers should be the driving force. Your users will regularly share feedback and make requests based on their collective needs, which naturally evolve over time. When a product changes too much, you risk alienating established users. Accordingly, offering a product that’s as simple as possible while providing core functionality will eliminate learning curves associated with continuous development.

“Use your customers, work backwards from their use cases, and then come up with a minimal and simplest form of an API that you can actually offer them,” says Vogels. That’s not to say that engineers are putting in minimal effort. Instead, you should aim to design user-friendly APIs that don’t overwhelm through complexity. Assign one call to one function, and expand your API to support other specialized calls. This prevents over-engineering and means that engineers don’t have to package everything together haphazardly.

4. Create APIs with Explicit and Well-Documented Failure Modes

Life’s good when an API works well, but what happens when it doesn’t? When a core function must execute despite roadblocks, APIs often leverage failure modes to prevent errors. CRUD APIs should be able to support a number of key operations when conditions aren’t optimal. It’s vital to document what happens when your API fails, and how exactly it does this. That way, API responses won’t be unpredictable, and developer users won’t be frustrated. Make these URI structures readily available for troubleshooting purposes. Input parameters and security concerns might also drive these inclusions.

5. Create Self-Describing APIs that Serve Clear Purposes

Simply put, developers shouldn’t be puzzled when inspecting your API. What the API actually does should be immediately apparent. Additionally, what can the API help your customers accomplish? It’s important to remember that APIs are productivity tools — ones that power user engagement, entertainment, business, or otherwise. Knowing and communicating which “lane” your API resides in will only boost its marketability.

6. Avoid Leaking Implementation Details at all Costs

APIs have immense business value, and the innovations behind them should be closely guarded secrets — especially as the microservices market grows more saturated. Keeping your implementations close to the vest is key. Otherwise, your customers who learn these details may become dependent on them.

Vogels warns, “they will start to figure out how you’ve actually implemented this under the covers, and will start to actually use that knowledge.” This also isn’t optimal because you’ll be unable to change your implementation. Customers can become reliant on “non-functional information,” which can disrupt your development pipeline, a principle we’ve covered on the blog known as Hyrum’s Law.

Conclusion

Now, why should we take the aforementioned as gospel? Well, Amazon is certainly not new to APIs. The company’s enduring technical background — and contributions to the programming space — have long influenced the entire cloud-computing industry. Founder Jeff Bezos’ 2002 API mandate set the course for future API development in a microservices context. Since then, Amazon has markedly impacted API consumption.

Werner hopes that these practices will spark both curiosity and conversation around best practices. API design is critical and not something to place on the backburner. He invites developers to read through AWS documentation to learn more and reconsider how they fundamentally approach the development process for the better.