GCP – APIs 101: Everything You Need to Know About API Design

Application programming interfaces, or APIs, are how software talks to other software. They abstract the complexity of underlying systems so the systems can connect in novel ways even if they were never intended to interoperate. Consequently, APIs are key ingredients in both most modern digital experiences and the execution of many of today’s most exciting business opportunities. 

How much value an API provides, however, involves not only the functionality and data to which the API provides access, but also how the API is designed. Many APIs are designed for integration—that is, as one-off projects that connect systems but do not anticipate future use of the API. The most valuable APIs tend to be designed to make developers’ jobs easier, which typically means designing them with the expectation they’ll be used by other developers in the future. This is designing for consumption. 

The distinction can significantly impact a business’s efficiency and ability to innovate. APIs designed for consumption make valuable functionality and data reusable, letting developers modularly mix and match different APIs to create new digital experiences or enable new strategies. For goals such as streamlining partner engagement or facilitating participation in digital ecosystems, being able to leverage APIs in this way is crucial. 

APIs designed for integration, in contrast, may serve the needs of an immediate project but do not help developers do much with the APIs going forward. These APIs may not be designed in ways that future developers will easily understand and may not behave in ways future developers expect. This can lead to the creation of new APIs, adding work and delay that could have been avoided if the older APIs had been designed with broader vision in the first place. 

How can API designers ensure they’re building APIs that will maximize value and developer productivity? We’ve explored this topic many times in the Google Cloud Blog, and in this post, we offer a collection of some of our most useful API design tips and best practices.

Different approaches: REST, RPC, and GraphQL

What an API even entails can involve different approaches to system interaction and different design norms, so overviewing various API design models is a great starting point. Check out API Design: Understanding gRPC, OpenAPI and REST and When to Use Them, Rest vs. RPC: What Problems are You Trying to Solve with Your APIs?, GraphQL: Building a Consistent Approach for the API Consumer, and Why Your Web APIs Should Be Entity-Oriented to dive in. 

Holistic API design overviews

For deep overviews of many API design topics, our ebook API Web Design: The Missing Link: Best Practices for Crafting. Interfaces that Developers Love provides a strong foundation, as does the Google Cloud API Design Guide, which has been used inside Google since 2014 and is the guide Google follows when designing Cloud APIs and other Google APIs. We also encourage you to read API Design Best Practices & Common Pitfalls, which summarizes a wide-ranging Q&A on API design. 

Specific Challenges and Best Practices 

Whereas the above articles address numerous broad topics, we’ve also explored many of the more granular and specific API design challenges that can impact an API’s long-term value. 

For example, APIs are in many ways about defining relationships. In a retailer’s API, the information model might address relationships among entities such as customers, orders, catalog items, carts, and so on. Similarly, a banking API expresses which customer an account belongs to or which account each credit or debit applies to. The most common way that API developers express relationships is to expose database keys, or proxies for them, in the fields of the entities they expose. However, at least for web APIs, that approach has several disadvantages over the alternative: the web link. To learn why, check out API Design: Why You Should use Links, Not Keys, to Represent Relationships in APIs. 

Similarly, when creating API URLs, it can be confusing — but impactful — to know when to use URLs built around names that are easy for humans to read versus when to use URLs that rely on static numeric identifiers. A bank account, for example, may be difficult to reliably reference if a numeric identifier is not used. Details about the account’s owner are all subject to change (e.g., name, address, marital status), or subject to ambiguity (date and place of birth), or both. Even if we have a reliable identifier for the owner, ownership of the account can change. A static numeric identifier is the most reliable choice—to dig deeper, read API Design: Choosing Between Names and Identifiers in URLs and, for a specific discussion of API design tradeoffs between human readability and system stability, don’t miss The False Dichotomy of URL Design in Web APIs.

APIs designed for consumption are essentially software products for developers, which means they may be iterated and improved, just as any software product is. Handling versioning of new APIs can involve some nuances, however, so be sure to peruse API Design: Which Version of Versioning is Right for You? and Common Misconceptions about API Versioning. 

Finally, APIs can impact how single-page applications are indexed by search engines—so if this sounds pertinent to your business’s needs, our two-part series on API design and SEO might be right up your alley. 

Doing more with APIs

You’re now well on your way to creating more powerful, user-friendly, and versatile APIs—and because the point of these consumption-focused APIs is partly to facilitate reuse, you’re also on your way to enabling myriad new ways to build richer applications more quickly. To learn even more about how APIs are driving business results, be sure to check out our round-up of API-related topics from Google Cloud Next ‘20: OnAir. We can’t wait to see what you build.