On the one hand, having proper API documentation can be a sign of early success for an API provider, allowing new users to effectively understand the functionalities and caveats behind an API solution.

On the other hand, extensive documentation could indicate an overly complex solution with far too many variables to navigate. Even in those situations where documentation is entirely warranted, of course, it can often be a hotfix more than anything else — the paperwork you dig up when something is broken and you can’t figure out how to get the API to do what you want.

This isn’t how it has to be. As Zane Claes of Airbnb stated during his talk at Nordic APIs 2016 Platform Summit, No documentation is the best documentation. To this end, many providers have begun to look towards new solutions for better user training and informing.

Today, we’re going to discuss a few of these solutions, and what they mean for the API landscape. We’ll discuss sandboxing as a means to onboard users, and the differences between fluid and static documentation. Finally, we’ll look at a real-world use case to see how powerful these implementations can be. While the end of API documentation isn’t coming, how we implement it is certainly evolving.

The Problem with Documentation

What, specifically, is documentation? In the most practical terms, documentation is simply a collection of descriptors and demonstrations by which a provider can educate a user as to the functionality of an API. This intrinsically assumes the following:

• The user does not, or cannot, initially understand the intricacies of the internal API, either due to complexity or obfuscation;
• If an error guide is present outside of standard network issues, the API is able to handle calls that will result in one of these errors; and,
• Documentation will be the prime point (or one of the prime points) for continued support of the user activity.

Documentation itself is not a bad thing, of course, but having complex documentation, especially complex static documentation, assumes that one or more of the preceding conditions are true. After all, the average person does not read the user manual for most consumer electronics, because the functionality is easily understood, and if they do read the material, they only do so when troubleshooting is required.

Most documentation describes the complex intricacies of the API functionality in a theoretical way. They’re static — rarely changing unless new features are implemented. Even when routinely updated, documentation is a conceptual solution, explaining the functionality without allowing for experimentation.

Caveat emptor — not all documentation is created the same. This piece is not attempting to paint the picture of documentation as a great evil — documentation is, after all, a pillar of the API community. What this piece is attempting to do, however, is demonstrate a better way.

Sandboxing as a Dynamic Documentation

One of these “better ways” is the idea of making fluid, rather than static, documentation in the form of sandboxing. Sandboxing in its base form is simply creating a controlled, known environment where users can test calls and functions against known resources.

Consider the difference between “memorization” and true “learning”. When a user has to resort to memorization of documentation or constant referencing, a problem is created in the break between resource and accessing that resource — the user is entirely dependent on the onboarding resource itself. With time, the user will become more and more knowledgeable, but the curve from beginning to end is one of extremity.

When a user learns, however, it is incredibly powerful. Learning comes from experience — instead of referencing a user manual, in a sandbox, the user manipulates data in real time, experimenting with mutations and variations in a way that you simply cannot truly do with plain documentation.

That’s not to say sandboxing is completely replacing documentation, of course — in this particular solution, documentation must be tied into the sandboxing environment in some way. Creating tooltips that show functionalities, creating a queryable, in-sandbox database of functions, or even simply creating several default, pre-made “test” queries can go a long way to informing the user as to what they’re doing.

A wonderful example of Sandboxing is the GraphQL API Explorer from GitHub. This GraphQL implementation sandbox allows you to test functionality within the sandbox environment, and demonstrates the ease by which a user can learn through interaction, rather than rote memorization.

Sandboxing is a leveraging tool. Documentation is always going to be around in some form or another — even with the problems inherent in most modern solutions, the fact is that documentation is required for effective user bases and implementations.

Given this, how do we use existing or planned documentation to sandbox?

Sandbox Implementation

Sandbox provides a way to generate interactive API manipulations.

Thankfully, sandboxing is somewhat “in vogue” lately, and because of this, there are a great deal of novel, easy to implement solutions to quickly craft mock environments. One such solution is the aptly named Sandbox.

Sandbox is an open-source solution for automatically generating mock RESTful or SOAP APIs and webservices. By using API definitions for what they term “instant deploy, collaborative build” API mockups (which is just a fancy name for a testbench or sandbox), the solution allow developers to push new revisions and test quickly.

The core attribute of Sandbox, though, is the idea of presenting a controlled mock of the live API to the consumer. Using intelligent tools baked into the solution (such as dynamic responses), the developer can guide a new user rather than throw them into the proverbial deep end.

Sandbox pulls directly from API documentation (specifically Apiary, Swagger, Readme.io, RAML, Gelato, WDSL, and Stoplight) for its auto-generation, which makes it highly attractive to long-term developers who want a sandbox solution, as it removes a lot of the barrier to entry and replaces that barrier with automation.

Most importantly (to some) — this solution is entirely open source, which makes trusting it to handle even secure APIs a much more safe proposition.

The key here is to make an environment where a user can experiment and learn, rather than simply memorize. But is sandboxing the only solution to this problem?

Exploring as Learning

We learn through experience.

Manipulation through sandboxing is only a single approach. Another source of learning is the idea of exploration. Whereas sandboxing relies on the user manipulating and interfacing with a live, self-enclosed mock of the API, exploratory solutions, conversely, focus on making the API and all it is parts more open to boot.

By exploring the relational constructs that drives an API and seeing how each element ties into another through calls and mutations, the user can get a “higher level” understanding of the data at hand, how it is processed, and how to interface with the system in a beneficial way.

Just as with sandboxing, however, exploration is simply a different approach at presenting documentation. Exploration fixes static documentation not through a layer of obfuscation like in sandboxing, but by guiding how the user is presented the information that they consume — the content is presented in a way the author intends it to be presented, specifically in the exact way it was coded (with all the implied reasoning within).

Exploration Implementation

The GraphiQL console is an example of exploratory API learning.

A more exploratory solution to API documentation is the GraphiQL API explorer. GraphQL is a powerful query language that was created by Facebook. Its main power lies in the fact that it creates a commonality between client and server, and allows for data fetching and manipulations in a much more streamlined, efficient way.

GraphiQL builds upon this relational conceptualization to present GraphQL APIs in a consumable, understandable way. One of the best benefits of how GraphiQL does this is the fact that tooltips and other information are natively integrated, rather than added afterwards as in sandboxing solutions.

GraphiQL generates a “pane” in the exploratory view, linking resources to the functions that interact with them, and giving real-time insight into the nature of the data being interfaced with. This also extends to initial coding and manipulation, preventing errors from building and giving helpful hints and tips as the user continues through the pane.

A huge benefit of this approach is the virality of the generated exploration — GraphiQL saves sessions, and can share these with others to show bugs, demonstrate effective solutions, and even implement new, theoretical solutions to long-standing issues.

This is markedly different from sandboxing, which is often a “navigate and wipe” prospect, where the work done in a sandbox is erased when the user exits the window or application. Because of this, GraphiQL is somewhat better suited for long-term exploratory learning, whereas sandboxing is somewhat better suited for on-the-spot experimentation and examples of pre-existent documentation.

Fluid vs Static Documentation

While these two methods are different in many ways, they do bring up a basic philosophical question that the API space needs to answer — do we really need (or want) fluid documentation? And more to the point, is fluid documentation worth it?

What we’re talking about here is a matter of changeability. Static documentation is just that — unchanging unless pushed as a big update, a constant bastion of information as dependable as the sun rising in the morning, in simple, plain English. There’s no fancy interfaces, no complex sandboxes — just a simple “cause and effect” documentation.

Fluid documentation, on the other hand, stands in stark contrast, ever evolving, exiting out of the standard GitHub readme or wiki site and entering the world of sandboxing and variable exploratory solutions. Calls have variable responses, so why should they be represented by static content? Fluid documentation says “it shouldn’t”, and would rather present the data relationally rather than simply stating “if this, then that”.

So what’s the issue, then? Is it really that simple a difference?

There is of course the problem of authority. When a user interfaces with documentation, what they’re doing is seeking information, and there’s something to be said for static documentation in this realm — when data is unchanging, and presented in an easy to read format, learning is standardized. Every user learns the same thing, in the same way, and thus is a predictable and supportable entity.

And then there’s the problem with integrity of data. When data is changed constantly, especially in documentation, users can end up thinking their variation is the true method and forgoing the “new” method featured in the dynamic documentation.

Finally, there’s concern over privacy. In order for a secure API to benefit from exploration or sandboxing, the provider must ensure that the interactive queries do not call functions that might otherwise be banned for certain users.

The truth is, even with all of these faults, dynamic solutions are still the best, as long as they are given the proper space to function. The best approach is a two-tiered one — providers should always provide static documentation for the meat” of the API, while using a sandbox as the front-facing user onboarding mechanism.

By supporting this two-lane approach, you can get the best of both worlds — you receive the usability benefits of an onboarding scheme with dynamic data, along with the reliability of static documentation.

Final Thoughts

As with any technology or solution in the API space, there are many number of variations as to how these two principles can be implemented. The simple fact is that joining static and dynamic documentation is more powerful than either component alone, and endlessly more useful for the average user.

Not only does the joining of these two solutions result in more effective learning, it results in more effective onboarding of potential users from both angles, allowing you to optimize your service to those who prefer to read to learn and users who prefer active experimentation.

Most importantly, these two solutions are not mutually exclusive — a developer can, if they so choose, implement them side by side, leveraging the strengths of each to cover the weaknesses of others. That’s the beauty of this approach — it’s entirely extensible and modifiable, and with that customization, extremely powerful.