An API is only as good as it is known. Getting an API into a developer’s hands, demonstrating the power of your solution, and providing an environment in which they can test and manipulate data in a controlled, monitored way is perhaps one of the most important unsung heroes of API publication.

Having an awesome, functional demo for your API is a great idea, as it provides a way for potential users to identify your endpoints and test their own code against it to see how the API behaves. Not only does this boost their understanding of your product, it also boosts their confidence that your solution is the way to go — the so-called “wow” factor.

In this article, we’re going to review types of API demos, specifically what an API Sandbox, Playground, and Virtualization is, as well as the benefits between each. We’ll showcase some examples of their implementation within select developer portals, and demonstrate how important they truly are.

The User/Consumer Barrier

There’s an important factor that’s often missed by developers that is key to quality API demos: the User/Consumer Barrier. This is the barrier a potential consumer has when adopting your product or solution. Bridging this divide is the most important facet of a business transaction in the API space, as it literally determines whether or not you have business and usage.

This barrier can be very difficult to cross sometimes, even when the API does something amazing. The main problem here is that the market is saturated — if you were presenting, say, the first economic fusion reactor, you’d have no problem getting users, because that is a small market with high demand. Developing an API, however, you’ll find difficulty in communicating that your email client does things better, that your data translator is quicker on encoding, etc.

The solution? Take a page out of the video games industry and publish a demo; demonstrate your product in a limited, controlled fashion. The differences in level of control is where we get our three topics for today.

It’s important to keep in mind as we move forward on this topic that we’re not discussing the development of a tradeshow demo, or a demo to showcase pet projects or cool features that developers personally enjoy — this is a huge business potential, and regardless of your choice among these three solutions, they should communicate and demonstrate the fundamental value and function of your API.

API Sandboxes

While their functionalities differ, the solutions presented here also all fall along a rather well-defined line — from most control to lease control. The differences between an API Sandbox, Virtualization, and Playground are essentially a slider between most control and most oversight to least control and least oversight.

Some key features of an API Sandbox — it often hosts a polished, interactive UI, is often paired with keen oversight, and is often limited only to a set of functions as provided and noted as ready for testing by the provider.

Accordingly, an API Sandbox can best be defined as thus: a platform that allows users and non-users to make and view the results of simple calls in a closed, walled-garden approach. While registered users would obviously be the best-case scenario, anyone can use a sandbox as the system itself does not handle significant volumes of private or important information, and by its very nature, is closed off from the rest of the API ecosystem.

That is not to say that, while it’s closed off, the data it generates isn’t used for the development track. In fact, the data generated from the sandbox is endlessly useful, and allows for a testing environment to be publicly shared with users while the API itself is being concurrently developed.

Think of an API Sandbox in the structure of a real-life sandbox in a playground. Parents hovering, always watching, kids are allowed to play and interact, but always in a guided, known way. The same is true within many API programs.

The other huge benefit of an API Sandbox is the mitigation of legal and ethical concerns. While an active system would be a hard sell to open up to experimentation, potentially by non-registered users, a walled-off, private system with strict oversight is a much easier sell, especially when none of the data is live, production data.

Finally, an API Sandbox boasts the benefit of being able to control variables that otherwise are not controllable. Lag can be simulated, DDoS attack defenses economically tested, and load balancing done on a scaled down system.

Sandbox Examples

Perhaps an API Sandbox with the most name recognition, the Microsoft API Sandbox is a perfect example of this approach. In this sandbox, Microsoft allows you to test your own calls and functions within the Microsoft Office 365 API suite.

Example: Microsoft API sandbox

This particular API Sandbox is actually one of a collection of sandboxes as well. Via the testing site, one can navigate to a variety of resources, the most useful being the Microsoft OAuth Sandbox, which allows you to test queries against a secure system to see how the API handles query, retrieval, and other basic, common calls.

The benefit here is multifold — not only do you get everything as stated earlier in this piece in terms of security and testability, you also get the huge benefit of allowing users to experiment and iterate, furthering their knowledge and by extension the bases of all those they interact with.

API Virtualization

On the other side of the slider, where control is reduced, you have API Virtualization. Whereas a Sandbox boasts controllability, a walled-in approach, Virtualization is the opposite.

When virtualizing an API, what you’re fundamentally doing is providing a copy of the API itself on a non-network basis. When virtualized, the API will run in the conditions it finds itself in and as if it were a real API. It will act as a “mirror image” of the final production API, allowing for accurate testing in a much-less controlled environment.

On the one hand, this is bad — data is more vulnerable to exterior issues, your API code is less controlled, and you’re essentially hosting a duplicate API if using the virtualization as a test bench for a development track. On the other hand, this is great — a truly real-world variant of your non-production code for testing and iteration, exposed to the very real-like circumstances it will likely be exposed to.

More to the point, API Virtualization is more accurate than an API Sandbox. Whereas a Sandbox mimics the behavior expected from the API functioning correctly, in API Virtualization, proper behavior is replicated — as is awkward behavior, errors, and faults in the API Architecture.

The choice between the two extremes (sans a “middle of the road” approach detailed later in this piece) comes down, then, to a simple question — how much control is desired?

When an excess amount of control is desired or necessitated by the data type and format (such as is the case with medical record and billing systems), then a Sandbox is more appropriate. Conversely, if less control but more real-world data points are needed, then Virtualization is the answer.

Virtualization Examples

Any API can be “virtualized,” but there are a wide variety of providers who can do this process for a provider. One such example is Axway’s API Gateway Platform, which provides a REST API Virtualization solution.

Axway’s interface for creating and editing a virtual API

The biggest benefit of Virtualizing the API using a service like the one provided by Axway is that a variety of security settings can be emulated and adopted to test the overall health of the platform, including the following listed on the official website:

• API Key
• Amazon Web Services Signing – Authorization/Query String
• HTTP Basic Authentication
• Invoke Policy
• OAuth (and External OAuth)
• Pass Through
• Two-way SSL

The main benefit here is obvious — in a Sandbox, while you get more control, you can only test against the specific situation you created for it. In virtualization, you test against a real-world variant with real-world security threats and implications.

API Playgrounds

An API Playground, then, is an “in between” approach. Whereas the Sandbox is a limited area, a very specific system with very specific rules, and a Virtualization is a production environment in all ways except being a production environment, a Playground is smack dab in the middle.

An API Playground mashes the benefits of both side of that slider quite well — while you get more of a real world dataset, it’s controlled and walled-in somewhat by controlling the variables upon which the system is emulated. If you want to simply test your API and reap both of the benefits of the previous methodologies, this is a great solution.

Playground Examples

A great example of this type of API system functionality is the API Playground at Apigee. Designed specifically as a “playground for API developers,” the service boasts four main features:

• Turn-key API development, allowing for almost immediate implementation and development;
• Mock server-set, allowing immediate API responses;
• Live testing of code as it’s coded;
• API Sharing using uniquely-generated URLs for intra-team development.

As you can see by how the service postures itself, the Playground is just what is sounds like — a somewhat walled-off but still wide playground. Sticking with our earlier metaphors, where an API Sandbox is a sandbox with parents hovering by, an API Virtualization would be more like a meeting of friends at a park. Extending this, an API Playground is somewhere between, with parents nearby and with certain assumed rules and expectations, all framed within a large, open space.

Apigee’s API playground allows mock API calls for testing purposes

Accordingly, Apigee’s solution is meant to provide a life-like solution without forcing the developer to resort to entirely open production testing.

Conclusion

Knowing all this, which type of API demo should a provider offer to help their developers? Ultimately, it comes down to that slider we’ve been talking about throughout this piece. How much control is really needed, and accordingly, how much real-life data do you want?

If control is needed and realistic data not a big deal, as is the case in basic iteration and feature testing, a Sandbox is a great solution.

On the other hand, if less granular control but more realistic testing is needed, as is the case with alpha/beta testing and stress testing, then the Virtualization approach is the best solution. If something in the middle is needed — which is often the case with smaller dev teams testing experimental features or transitioning out of early basic iteration and feature testing and into full-blown production — then a Playground may be more appropriate.

Whatever the exact implementation, the API demo will be a vital part of your developer center as it has the power to increase onboarding and usability, taking sample resources from the conceptual to something a developer can understand and physically interact with.