JavaScript documentation

Nick Houghton, October 20 2015


We have finally started updating our documentation, and the first bunch of changes are now live. While generally the least enjoyable part of the product development process for us, we’ve stop putting it off have started doing our homework.

Recent additions for this week:

How the require() function works, something that many people figured out by themselves, much like NodeJS our JavaScript files can import other files to create much more maintainable projects. Long overdue, but the docs now explain how it works.

Supported 3rd part JavaScript libraries available out-of-the box, again something many people dug around to find, we’ve now written it down. Also there is now a reference for when we add new or tweak existing 3rd party libraries.

Also tweaks to existing entries. Expect more updates soon!

Hit us up with any feedback, or raise a ticket on GitHub.

RAML Support

Nick Houghton, May 20 2015


We are pleased to announce we have recently added RAML support to the platform. Adding to the existing support for Apiary / API Blueprint, Swagger and WSDL.

Importing a RAML file to generate your Sandbox definition is as simple as clicking on the new RAML button on your Sandbox Dashboard. The only caveat is that like all the other API definition importers, the RAML file must be a flattened file that doesn’t include any external elements.

If you have a large RAML definition you will likely have followed best practices and broken your file down into many sub-files. If you are in this situation, you can use a library to ‘flatten’ your definition for you before importing into Sandbox. One of those tools is node-flat-raml.

Try it out now, and hit us up with any feedback, or raise a ticket on GitHub.

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.

Newer    Older