NOVEMBER 2018CIOAPPLICATIONS.COM 19promoting 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. Private APIs should be developed with a similar level of importance as those that are public. Clear definitions and accessible documentation prevent wasted developer time and help onboard new employees.Diagnostic API Stratum - SupervisorA 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.Consumer-focused Design throughout All StrataIn 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. Diagnostic APIs are rarely given much attention, but can bring great value if well designed and supported
< Page 9 | Page 11 >