A global company shares its ingredients for a holistic API

When businesses decide that they want to become an “API-first company,” the first big step is to create an “API-first strategy.” That involves big discussions around the architectural and technical aspects of building a scalable, reliable, and lightweight API.

However, at our 2019 Austin API Summit, Sandip Dhummad and Amit Patel from S&P Global Ratings spoke about how such an approach can potentially neglect the other side of the coin. They suggest that most API designers see that coin’s sides as follows:

• Growth: What will make my APIs a hit in the market like those of Facebook, Twitter, Google, etc.?
• Developer Experience: What makes APIs consumer-friendly and easy to use?

Sandip and Amit theorize that paying excessive attention to growth for growth’s sake, the first of the above bullets, can eclipse thoughtful and intuitive design. In other words, API providers that focus too heavily on tools and technology can overlook some of the intricacies of API design.

Below we look at a few of the points made by Sandip. Most of them are smaller details that developers might rush through. However, giving them adequate thought could greatly inform the direction of an API.

What is your API’s purpose?

Sandip suggests that one of the big questions businesses ask themselves is, “how important is this API for driving growth?” A valid question, no doubt, but not the only one at hand. He mentions two key strategic business benefits of implementing an API:

1. Attract blockbuster complements
2. Open windows to new ecosystems

To focus solely on growth as an outcome (i.e., attracting blockbuster complements) could be a mistake, as it deals with the desired destination rather than the journey itself. It might be smarter to think of growth as a natural outcome of people wanting to use your API.

Sandip provides the example of IBM and Watson:

“They [IBM] did not build an engineered system out of Watson. Rather, they made Watson available as a public API so people could explore. Now they are learning about how people go about using a cognitive system for their benefit.”

That approach to APIs might sound like a noble sacrifice, but it’s really not. There’s an implied benefit for API developers in fostering exploration and experimentation. As Sandip says, “when you expose your products and services as an API, you convert them into a platform… People can come in and start building their applications, opening a new window of opportunity for you: to learn and understand the value of your data.”

The Devil’s In The Details

Sandip describes how some API developers, rather than failing to see the forest from the trees, fail to see the trees within the forest. It’s easy to plan out an API and think, “OK, this is going to be a RESTful API, and we’ll use the OpenAPI Specification. Let’s get started!”… They fail to consider the smaller details.

Some of the examples Sandip gives include:

• URI: Treating URIs with care, using all lowercase and thinking twice before finalizing resource names
• Mapping: Considering the relationship between archetypes and action mapping
• Queries: Keeping query parameters consistent with URI or defining them based on data binding supported by backend languages
• Great Docs: API docs with inline test/try capability

We’ve written at length about the importance of API documentation before, but points like the above reflect more granular details. Providers must go beyond aesthetics to consider design best practices when constructing your API.

Smoothness & Security

Of course, building an API is just the first step towards actually offering it to consumers. Input data validation is an integral part of keeping your API running smoothly, not to mention its relationship with API security. Sandip makes suggestions like:

• Leverage cross-cutting aspects for data validation to avoid boilerplate code.
• Use data binding/validation frameworks for Java applications.
• Leverage consistent error handling mechanisms.
• Use input sanitization to protect against attacks like XSS, SQL Injection, Header Bomb, etc.

An API must perform well, respond with useful error codes, and meet security standards. Without these elements, developers won’t choose to place their trust in a service.

Power to the Consumer

Sandip also extols the virtues of flexibility and putting as much granular control in the hands of developer consumers. For example, it’s smart to keep mobile in mind. Issues like over and under-fetching, as well as service and version sprawl, can plague API consumers who are trying to work within the context of mobile platforms.

• Fetch selected fields only, with partial responses for mobile clients.
• API consumers may know the shape of an object needed better than the service provider.
• The absence of partial response capability undermines the effectiveness of mobile API usage.
• Allow for the definition of fields to be retrieved by API consumers, ensuring that mandatory fields are always provided.

It bears repeating that, in the case of an external API, it’s crucial to keep consumers happy. Productized APIs must inherently meet certain expectations.

Speed and Streamlining

Using an appropriate framework and technology should, theoretically, keep your API running at a good speed. However, once again, overlooking specific finer details can result in an API that’s sluggish or breaks mid-call.

When trying to speed up your API, Sandip and Amit suggest the following:

• Enable response filtering based on the application context, giving your consumers more free rein for building applications.
• To avoid extraneous network traffic, implement pagination (offset pagination or keyset-based/continuation token) when returning multiple items.
• Consider client-side/server-side caching to speed up API performance.
• It’s good practice to compress service responses, especially for methods returning a collection of objects, using a compression algorithm or framework support.

In the world of technology, speed is king; if there’s a way to speed up the performance of your API, then doing so is a no-brainer. Most webmasters regularly check their page speed performance. There’s no reason API developers shouldn’t monitor and optimize their APIs in the same way.

Final Thoughts

We’ve said it a thousand times before, but it bears repeating: there is no “one size fits all” approach when it comes to building an API. Sandip and Amit, when offering up real-life examples at our Austin API Summit, and their audience know this as well as anyone.

The message we took away from his talk, however, is that some API developers become fixated on platforms and tools at the expense of certain granular details.

That’s why it’s good to consider best practices for things like security and API documentation while still in the planning stages.

Fail to do so, and you may end up with an API first redesign that, while it does indeed put the API first, puts the consumer so far down the list that there’s no way they’ll stick around.