API documentation can exist in many forms and may range from static document-based reference material for passive reading to a fully immersive and interactive learning experience. Neither is inherently better than the other and each may be better suited to different types of learners.
In addition, an API publisher may provide documentation that is targeted at machines instead of human users. The WSDL description format for SOAP services is an excellent example of this type of machine readable interface documentation. Machine documentation is useful when appropriate tooling exists (as is the case for SOAP), but outside of the SOAP world, Web API client-side tooling is neither widespread nor is it standardized. API designers exposing these kinds of interfaces need to avoid making a machine readable document the sole mechanism for learning because it presents a high barrier for human comprehension.
The key when choosing a documentation strategy is to consider the consumption of the material from the user's perspective. For example, users who are encountering an API for the first time will prioritize simple tutorials and examples that reduce the time it takes to make the first successful API call. On the other hand, developers who have reached an intermediate or expert level will be more interested in an indexed list of resources with more-complex examples.
Beyond the immersion level of the learner, a designer should consider the characteristics of their primary developer targets. This includes determining their platforms, programming languages, the organizations that they belong to, and even the goals of the end-users they are building applications for. This understanding should ultimately shape the vocabulary, examples, and descriptions of the API to suit the mental model of the target user base.
Of course, the design decisions that take the most time and get the most attention are the ones related to the Web interface itself. API designers must create an interface that provides the core level of functionality required for their users to do what they need, but in a way that requires as little learning as possible and prevents the system from acting in an undesired or unexpected manner.
This includes big decisions regarding the protocols, message formats, and architectural style, as well as a multitude of smaller decisions such as the names and number of parameters, the size of responses, and the relationship structures for entities. Whenever possible, design choices should be informed by the particular developer-user perspective being targeted.
Within the Web API world, human-readable documentation has been established as the conventional way to provide a view of the interface itself. Developers who have experience using REST or HTTP-based APIs expect that some form of documentation will be provided to aid them in the learning stage
Invocation is the first chance for developers to interact with the runtime of an API that has been created rather than simply extending their base of knowledge. Invocation usually involves writing and running client code to test a function. It provides an opportunity to get feedback from the interface and validate assumptions about how the API actually works.
It turns out that this feedback mechanism is essential to learning, but having to write client code presents a barrier to receiving immediate feedback. As a result, usability-focused APIs will often offer shortcut mechanisms to make it easier for their users to push, pull, and prod the API. For example, an API provider may offer its developers a Web-based "API explorer" tool that allows users to dynamically generate interface requests, invoke the API, and view the results all without writing any code.
Feedback from API invocation is essential, because it is the primary way that developers are able to "sense" the interface they are using. But, feedback is only useful if it is both meaningful and helpful to the user nonsensical error codes and silent responses do not improve usability. Instead, an API invocation should result in a response that informs both the application client of the runtime result and the human developer who coded the client.
API designers may choose to provide usability aides to make the development of application clients easier. For example, sample code and sample applications make it much easier for prospective developers to write their own applications. Going even further, API owners may choose to provide entire client libraries or SDKs to simplify the act of invocation as much as possible for their primary users. From a developer perspective, an SDK shifts the API experience from a network or HTTP-based syntax and vocabulary to a local programmatic interface with an application-specific vocabulary.
For example, developers making calls to a typical HTTP object-based API will need to learn the names of resources, the HTTP methods allowed for the API, and then determine how to make the call over the protocol and serialize objects into requests and responses. However, when given an SDK, they can focus simply on the local invocation required to accomplish their goal.
Usability aides and tools provide great usability uplift, but there is a development and maintenance cost associated with each of them. This cost can be particularly taxing in the Web API space because multiple platforms and programming languages often need to be supported. As a result, it is wise to limit development of usability aids to a small number of high-priority user categories and provide a more generic HTTP-based API for the remainder.
Analysis, Troubleshooting, and Support
Learning and invocation-based interactions enable developers to build client applications; however, an additional level of interaction arises after construction is complete. How does the developer determine the level of activity and usage for the application? How does he get a sense of the invocation performance or the pattern of calls that his application has made? Whom does he contact if the API itself is underperforming or is no longer available?
These interactions should be supported with the same usability focus as the rest of the API; otherwise, an organization risks losing active users and increasing operational risk. Self-service analytics tools that permit developers to view and visualize their apps' invocation data are important. It is also useful to provide data about the API's operational statistics and be transparent about the availability and health of the interface. APIs that provide insight into uptime, performance metrics, and outages build a sense of trust within their developer community.
Formally adopting usability design practices for Web APIs can be expensive and labor-intensive, and many API designers may struggle to acquire the necessary time and resources for proper user testing and surveying. But even the simple acknowledgment that usability is a feature can have a positive impact on the end result if it permeates the interface design culture of an organization.
Developer-centric interfaces that offer high quality documentation, interactive components, SDK aides, and analytics are winning over developers and reducing the time to market for applications.
As APIs become as ubiquitous as electricity and telephone systems for businesses, the focus on growth and productivity goals will increase. Organizations that embrace a user-centric approach to interface design will reap benefits, while organizations that lack empathy for their API users may be left behind.
Ronnie Mitra is the director of API design at Layer 7 Technology's API Academy.