APIs built for consumers, not systems

Many of the companies that we have worked with over the years have created SOAP-based services (SOA) in order to serve distributed computing demand. However, they have struggled to realize the promise of reuse or easy consumption. The common hurdles that they experience are:

• The documentation is not self-evident to the consuming developer. Documentation (WSDL) is commonly created from code and lacks the detail needed to successfully understand the service requiring many hours of technical expert support to successfully integrate.
• The structure is not self-evident to the consuming developer. The structure of requests and responses are not understandable from the WSDL. Behaviors are hidden in the code and the WSDL, generated from the code, is rarely supplemented to overcome this gap.
• The naming conventions are not self-evident to the consuming developer. Field and object names in the operations are team or systems-oriented and require systems expertise or tribal knowledge in order to understand what they truly represent.
• The service is not purpose-built for the consuming developer. Services are typically designed and built based on systems of record or technical processes and rarely represent the consumers’ specific application demands requiring the consuming developer to execute orchestration and acquire business rule understanding that is unnecessary complexity.
• The service does not represent business capabilities that are used over and over by consumers. Since the development teams are required to work closely together to overcome these challenges the result is usually a tightly coupled solution that is rarely reusable or reusable but not ideal.

Consumer-focused design

One of our clients is currently making the change from SOA to API and I think their first API will serve as an excellent example of how our API designs and systems architectures could change to be more consumer-oriented.

The first service that they are going after is a store hierarchy service. The current data sits in a shared database with an application that sits in front of it to allow for many hierarchies to be stored in a single data structure.

The first service design path that was created mirrors the hierarchy business system that it represents.

And the return structure for the hierarchy request was represented as:

The path structure is RESTful and the JSON is well-formed, but this is not an API. APIs are built to solve consumer problems and are self-evident representations of business capabilities.

After having a long discussion with the product owner, we were able to derive the following use cases for the API:

• As an application, I need to retrieve the entire store operations hierarchy for the entire company.
• As an application, I need to retrieve a store hierarchy for a specified Country
• As an application, I need to retrieve a store hierarchy for a specified Division
• As an application, I need to retrieve a store hierarchy for a specified Region
• As an application, I need to retrieve a store hierarchy for a specified District
• As an application, I need to retrieve store details for a given store
• As an application, I need to retrieve a list of stores for a specified Country
• As an application, I need to retrieve a list of stores for a specified Division
• As an application, I need to retrieve a list of stores for a specified Region
• As an application, I need to retrieve a list of stores for a specified District

Many more use cases will surface as the API matures, but these are the use cases that represent the initial demand for the service, so that’s where we start.

With that understanding, we were able to change the path structures to look more like this:

The benefit is that the names are now clear and understandable and represent specific resources that the consumer is trying to use.

We changed the hierarchy graph to look more like this:

This design is not infinitely recursive and it doesn’t represent just any hierarchy. It represents a finite structure for a store operations hierarchy that is self-evident, uses language that is understandable by the consumer and presents the structure in a way that makes the data relationships clearly understandable.

Summary

APIs are not just about REST. APIs are about packaging your business’s capabilities so that they can be autonomously consumed and rapidly evolved to meet the accelerating demand of channel consumption. So, don’t get caught up in the tech. Keep your eyes on the goals. Create APIs that solve consumer problems, are easy to use by consuming developers and can change to meet the changing demand of your channel customers.

Learn more about how to design great APIs.

About the Author

Lou Powell brings a steadfast drive for innovation to his role as partner at Concentrix Catalyst, a Google Apigee agency that was awarded a 2019 Apigee Partner of the Year distinction. At Concentrix Catalyst, he works closely with businesses to create pioneering experiences and accelerate outcomes, unlocking greater value and market leadership. He worked in advertising and digital marketing before launching his own business, Vanick Digital, which he led for 19 years before acquisition by Concentrix Catalyst. Lou is a lifelong student of technology pattern adoption and the practices of tech natives, and he brings a design-thinking approach to technology in all of his work.