A featured contribution from Leadership Perspectives, a curated forum for enterprise technology leaders, nominated by our subscribers and vetted by the CIOApplications Editorial Board.
Dell EMC
Maximizing Value with API Consumer Strata
Public API Stratum - Customer
A public API is targeted at the widest audience and has the greatest potential for direct revenue. For example, retail customers expect organized shelves, clearly labeled prices, and a register at the end to pay for their goods. Similarly, consumers in the public API stratum expect an offering to provide functionality and data available within your application. These APIs can be pay-as-you-go, hosted in the cloud, on a private network, or wherever automation and data access outside your application are necessary. It’s to your advantage to make your public API intuitive, satisfy consumer expectations, and enable self-help. Doing so reduces consumer frustration, minimizes support costs, and increases usage— which is why you created the API to begin with!
Private API Stratum - Employee
A private API is targeted at developers, applications, and services within the same company or close partners. For example, retail employees work together to accomplish tasks, have access to the “back room,” and ultimately have a responsibility to serve the customer. Similarly, consumers in the private API stratum may require more privileged access than what the public APIs expose. Private APIs can bring great value to an organization by connecting products together, promoting functionality or data reuse, and helping serve other sets of customers. Unfortunately, this level of API often receives less attention to design and ease of use because it’s not customer facing and may just be “good enough” for now. This shortsighted view will increase operational costs when other teams can’t figure out how to use the API or it constantly needs revision to fit an ever changing list of requirements.
Diagnostic API Stratum - Supervisor
A diagnostic API is most useful to test and support your application. For example, retail supervisors may occasionally override pricing, run reports for business performance, and make store-wide changes. Similarly, consumers in the diagnostic API stratum can make changes no one else should, get information that helps assess problems, and provide access to internal data or processes. Diagnostic APIs are rarely given much attention, but can bring great value if well designed and supported. Example uses for a diagnostic API include changing parameters to test for errors or shorten test cycles, bulk loading data, and gathering detailed operational metrics. Although these interfaces have a relatively small audience, it is critical they are well documented and secured from misuse.
Diagnostic APIs are rarely given much attention, but can bring great value if well designed and supported
In whatever stratum a consumer resides, their expectations should be satisfied by an API designed to effectively meet their needs. It’s not sufficient to just expose your application’s internal data structures through an API. Unfortunately, this is how many application developers create their APIs. A consumer-focused API will present data and methods in a form most useful to the consumer, regardless of how this is handled within the application. Sufficiently abstracting the internal details of your application also gives you the freedom to make changes without impacting your consumers. The separation between consumer strata does not imply separate API instances. Role-based access control within a single API should be used to enforce appropriate limits. However, documentation should be filtered along the lines of consumer strata to prevent confusion over what is available.
Even the most intuitive API design must be clearly explained through a “Getting Started Guide,” tutorials, example code, and consistent API Reference Documentation. Potential consumers should be able to find and start using your API within minutes. Tutorials and example code help guide a potential consumer through typical usage patterns, giving them a base workflow to copy and adjust as needed. Once a consumer is comfortable using your API, they should be able to discover more information through your reference documentation, which is expected to define the totality of what is available to them. Producing these various forms of documentation will likely increase initial development time but reduce support and maintenance costs.
Creating a consumer-focused API begins by determining typical interactions, preferably in the form of user stories, for defining the data and workflows expected. The API is then designed around these interactions by defining a contract between the API producer and consumers. From this definition, a good portion of implementing the API can be automated. Automatic test validations ensure compliance with the contract, reference documentation can be generated in various forms, and even portions of the application code are created with no additional effort. An additional benefit of creating your API definition early is that consumers don’t need to wait for an API to be released - they can use the definition to perform their work in parallel.
Customer-focused design may make sense for public APIs, but applying the same principal to private and diagnostic APIs tends to be ignored. There is lost opportunity and operational cost in organizations that treat private and diagnostic APIs as a development byproduct rather than a valuable resource for collaboration and sustainability. APIs created to focus on the expectations of their consumers, of any type, will bring clarity and efficiency that benefit both sides of the interface.
