Can a Mock Server be an API Sandbox?
What are the differences between a mock server and an API sandbox?
Offering an API sandbox as part of your documentation is mandatory. Not only does a sandbox let potential consumers try the API before actually signing up to use it, but it also gives them a powerful tool to run contract and functional tests. "One way of offering real examples is to provide a sandbox where consumers can experiment with interacting with your API," I wrote. Setting up an API sandbox is, therefore, something you need to get sharp at. And, if you don't have enough time or resources, you'll certainly want to look for a simple solution such as a mock server. But can it deliver the same functionality as an API sandbox does? Stay with me to find out.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
Setting up an API sandbox is difficult. There, I've said it. An API sandbox has to feel like the real API. But, at the same time, it needs to offer consumers the freedom of experimenting without the fear of losing data. To make a sandbox environment credible, it should have a storage infrastructure similar to the real API. In other words, whenever consumers read from the API or write to it, the data flow should be similar to what would happen in reality. So, for example, if your API exposes a payment operation, your sandbox should also do a credit card validation, even if its result is fake. If your API lets consumers buy products, every item added to a shopping cart should decrement its availability. I think you get the point. The sandbox has to fully simulate how the real API would behave. And that is why, in my opinion, it's so difficult to put together a sandbox.
One solution, though, is to simply use an API mock server. While it doesn't go all the way to provide a simulated reality, it can be good enough in some situations. One of those is the case where you have a read-only API. If consumers can't manipulate data, there's a lot less functional area to cover. You can focus on providing data that looks like what the real API would deliver and making sure all functionality is available. The functionality that matters here is related to things like filtering, sorting, and pagination. If you can put all those into a mock server, then you're done. Anything more sophisticated will need more effort to set up. Either you launch an API simulation, or you set up a full sandbox environment that resembles the real one, but using fake data not connected to any production systems. An API simulation could be a good solution because, in theory, it's easier to put together than a full API environment. The important thing here is to understand that, in many cases, an API mock is not enough to provide a proper sandbox
A few months ago, I was on a project where we needed to offer an API sandbox. I remember we had to choose between offering a mock server or a full sandbox environment. We didn't have much time to spare, and our resources were limited, so we opted for an API mock server. Over time, it became clear that a mock server wasn't enough. And it wasn't enough, not because the mock server didn't resemble the API. After all, it was a read-only API. The challenge, in our case, was that the data didn't feel real to consumers. Fine, they were able to filter, sort, and paginate. Over fake data that didn't feel real. After moving to a hybrid solution where we fed the mock server with anonymized real recent data, usage went up, and consumers got happier. In this case, the solution wasn't complicated and just involved using real data as the source of the mock server.
There are cases, however, where a sandbox has to have more than just what a mock server can offer. One drawback of having a mock server is data recency. If you don't update the data that the mock server uses, consumers will feel they're dealing with a fake system. This will hurt particularly if your API responses include dates, as you can imagine. Another issue with most mock servers is their lack of ability to persist data manipulated during API requests. Whenever consumers make a request to a data creation operation, they want to see that reflected in subsequent API calls. Consumers don't just try isolated operations. They want to see how the API adapts to their full workflows. And, for that, you need to have some sort of data persistence in place. But setting up a full sandbox environment with databases and other components feels too heavy.
I don't think you should have a sandbox unless you can offer data persistence. So, either use a mock server that can save the data consumers send during requests, or implement a full sandbox environment. In the end, offering an API sandbox that doesn't feel like the real thing will hurt the trust consumers put in you.