Re-import your API definition into Sandbox

Nick Houghton, May 11 2015


This month’s platform update brings support for re-importing an API definition into an existing Sandbox. A number of people have asked to be able to re-import an API definition (like Swagger, Apiary or WSDL) to support their workflow better as their API changes over time. The first version of this is now available.

The first version of this feature works as a destructive re-import, re-importing a new version of your API definition will clobber any changes you have made since your initial Sandbox creation. This doesn’t suit everyone’s use case, obviously only supporting those who make few changes to their generated definition and are will to migrate them manually. We realise this and are already planning the next revision where the re-import process will combine the new API imported definition with any changes you have made to enhance the function of your Sandbox with the since the last import, but that is obviously a much more complicated undertaking.

There are a number of other minor updates and tweaks that have gone on this month, the most noticable of which is cleaning up some whitespace / newline artifacts left behind by the liquid templating process. Previously liquid tags would leave behind any whitespace that surrounded them, potentially leaving many ugly empty lines in your final output, these new lines are now automatically removed and your responses should be much cleaner.

{/% for i in items %} <-- Rendered as an empty line -->
{/% endfor %} <-- Rendered as an empty line -->

will now render as


Try it out now, and hit us up with any feedback.

Clones and Forks

Nick Houghton, April 26 2015

We’ve built Sandbox to support many different test scenarios and to be used across teams. Today we’re going to look at two key features that enable this: Clones and Forks.


When you create a Sandbox, manually or via an import, it is created with route definition files (.js and .liquid), a Git repository, a state store and a unique HTTP endpoint. At this point you can add, edit and enhance your Sandbox to fit your test scenarios and that might be enough for your needs, but if you work in a team, or want better coverage you don’t have to stop there.

A clone is a new Sandbox that refers to the original. It has a new unique endpoint and a separate state store from the source Sandbox, but refers to the same definition files and thus has no Git repository (only the original). Any change to the original definition files will be reflected on all unique endpoints, the original and any clones that may be created off it.

Clones can be really useful to support a couple of different test scenarios, the first is allowing each tester or client to have their own Sandbox environment. For example if you have a team of a couple of developers and a few testers, each tester could have their own Sandbox environment to test the application against. This not only lets them keep their Console activity separate for easy tracing, but if your Sandbox is stateful the clones let the testers work independently of each from a data point of view, which depending on your process could be a showstopper.

The second important clone use case is around negative testing. Because Sandbox clones share their definition files, it is possible to create a primary Sandbox to test positive test scenarios and then one or more clones to support failure scenarios (like an HTTP timeout). Using clones this way lets you achieve greater test coverage of areas where you typically might not have any coverage at all, these kind of negative tests are often the hardest to cover.


A fork, much like in Git parlance, is a new Sandbox copied from the original. For all intents and purposes it is a completely separate and disconnected Sandbox (repository, state and endpoint), but the route definitions are copied across from the original at the time when the fork is completed.

A fork is useful when you have a Sandbox that might fulfill part of your needs functionally, an old version of an API for example. But you need to enhance that function further, or modify its behaviour in some way. While a clone gives you a unique endpoint, you cannot modify any of the definition files, to make modifications you have to edit the original. A fork takes a copy of the definition files at that point in time, letting you then make whatever modifications you need.

This can be useful in a number of scenarios, for example if you have a base Sandbox and want to quickly try out a new change without impacting existing consumers. However because a fork is permanently disconnected from the original Sandbox you should avoid making changes you want to keep in a fork, try and incorporate it into the original.

We will have a future post showing in more details how to use clones to cover negative test scenarios, and how it can help you. In the mean time give it a try, and hit us up with any feedback, questions or problems.

Generate mock data more easily with Faker library in your Sandbox

Nick Houghton, March 23 2015

Data generation helpers

This month’s platform update brings support for data generation helpers in the form of making the Faker library accessible to all Sandboxes. Generally when building stubs you want your stub data to represent the values created by the real system, but when it comes to addresses, names, emails, phone numbers etc it is easier to hard code one than generate a new realistic value everytime.

With this month’s platform update you can now use the Faker library to generate realistic data for many different properties increasing the value and accuracy of the Sandbox stubs you are creating.

There are quite a number of different properties available some of them include:

  • firstName
  • lastName
  • fullName
  • phoneNumber
  • email
  • city
  • streetName
  • streetAddress
  • streetSuffix
  • country
  • state
  • latitude
  • longitude
  • lots more!

Using the Faker library is simple, it is available to any of your JS code as a global variable already, no need to load or require() it in.

Sandbox.define('/test', 'get', function(req, res) {
// send a random state as the response

The full list of available properties, including more details on functions and usages is available on the Faker page.

As well as data generation helpers, we’ve added CORS support to the Sandbox Runtime component available here, which should help everyone testing JS apps locally, and a bunch of bug fixes across the platform generally.

Try it out now, and hit us up with any feedback.

Automatic syncing of Sandbox definitions to Github

Nick Houghton, January 6 2015

This month’s platform update brings support for automatic two-way syncing your Sandbox definitions (main.js etc) with a Github repository of your choice and some API Blueprint importer bug fixes.

Two-way Github Syncing

Defining and having your stateful Sandbox stubs always running and testable in the cloud is great, but in a perfect world the stub definition should be in Git, versioned alongside your code and most importantly, your tests!

The new two-way syncing feature solves this problem for you. You can configure, at a Sandbox level, which remote repository and what subpath inside that repository you want the sync with. Once configured any change in the remote repository (under the chosen subpath), or change in the Sandbox platform will trigger the synchronisation.

The external repository syncing is available in the Sandbox Settings -> External Repository page. It requires that you grant OAuth permissions to your Github account, we use this to list your repositories, branches and to commit changes into your selected repository.

Importantly the syncing process only checks out the files and folders under the given subpath, /test/stubs for example. So none of your other code, configuration etc will be ever copied to our servers.

At the moment this syncing feature only supports Github, but Bitbucket support is planned soon.

Try it out now, and hit us up with any feedback.

Importing Apiary and Swagger

Andrew Stewart, October 20 2014

This month’s platform update brings support for generating mock services from Apiary and Swagger documentation, and an improved code editing experience.

Generate Sandboxes from Apiary and Swagger

If you’ve invested the time and effort to design your web API with the excellent tools available from Apiary or Swagger, you can now import your API design spec to generate a mock API implementation with Sandbox - getting your development teams up and running even quicker. Try it out now

We love designing APIs with Apiary however their mock server only provides simple canned responses. You can now add custom behaviour, dynamic responses and more when you import your Apiary API spec into Sandbox.

We’ve added support for Swagger too, with support for more formats coming soon. Hit us up with the format you’re after and we’ll prioritise it.

Improved code editing experience

You’ve probably noticed that the dashboard and coding experience have undergone an overhaul. Everything you need to code, inspect and debug your sandboxes and API integration problems is now available on a single page.

Sandboxes now support splitting your code into multiple modules. If you’re familiar with NodeJS require to import modules then you’ll know how to work with Sandbox imports right away. See the docs for more details.

Forking Sandboxes

Creating sandbox clones is a great way to ensure tests can run in parallel with completely isolated independent data and now you can tweak the behaviour of a sandbox without affecting other clones. Forking a sandbox provides you with your own copy complete with a Git repository to push changes too. Note that your forked sandbox will no longer receive updates from the original. Any sandbox you have access too can be forked from a sandbox’s project page.

We always welcome feedback from our users, reach us at twitter.

Newer    Older