DEV Community

FetchSandbox
FetchSandbox

Posted on

When your SaaS API has docs but no real sandbox

#api #saas #testing #webdev

A lot of small SaaS APIs have decent docs.

Some even have an OpenAPI spec.

But no real sandbox.

That sounds fine until a developer tries to integrate the API and needs to test the part that docs cannot prove:

Does the workflow actually hold together?

Not one request.

The workflow.

The problem is not the first 200

Most API docs can show this:

POST /customers
→ 201 Created
Enter fullscreen mode Exit fullscreen mode

That is useful, but it is not enough.

For a real SaaS integration, the next questions are usually:

Can I read the same customer back?
Does the subscription attach to the right customer?
Does the webhook fire?
Does my app know which user should get access?
What happens when the subscription is canceled?
Enter fullscreen mode Exit fullscreen mode

This is where a docs-only API starts to feel thin.

The integration does not fail because the endpoint is unknown.

It fails because the lifecycle is not testable.

The workflow small SaaS teams should expose

If I were building a small SaaS API, the first sandbox workflow I would expose is boring:

POST /customers
  → create a customer

GET /customers/{id}
  → verify the customer exists

POST /subscriptions
  → attach a plan to that customer

GET /subscriptions/{id}
  → verify state is active or trialing

webhook: subscription.created
  → let the developer test access control

PATCH /subscriptions/{id}
  → cancel or pause

webhook: subscription.canceled
  → verify access gets removed
Enter fullscreen mode Exit fullscreen mode

That workflow is not flashy.

But it answers the question every integration needs to answer:

Can my app keep its local state aligned with the API provider's state?

Why examples are not enough

Example responses are static.

They can show what a customer looks like:

{
  "id": "cus_123",
  "email": "buyer@example.com"
}
Enter fullscreen mode Exit fullscreen mode

But they cannot prove the next request will remember it.

They cannot prove a subscription belongs to that customer.

They cannot prove the webhook event is shaped the same way as the API response.

They cannot prove your app removes access when the subscription changes.

That is not a docs problem. Docs are still needed.

It is a sandbox problem.

The failure mode

The most common failure is not dramatic.

It looks like this:

customer create works
subscription create works
webhook handler returns 200
Enter fullscreen mode Exit fullscreen mode

Then two weeks later:

paid customer has no access
canceled customer still has access
support cannot map billing ID to app user
webhook retry created duplicate state
Enter fullscreen mode Exit fullscreen mode

All the individual calls looked fine.

The workflow was never tested.

Why small SaaS APIs skip sandboxes

I understand why this happens.

A small SaaS team is usually trying to ship the core product first.

Building a second environment with fake accounts, seeded data, fake billing states, webhook retries, and lifecycle transitions is a lot of work.

So the API ships with:

  • docs
  • examples
  • maybe an OpenAPI file
  • maybe test credentials
  • maybe a staging workspace if you ask support

That helps.

But for developers integrating your API, the missing piece is still the same:

Can I safely run the lifecycle before touching production?

A better minimum sandbox

The minimum useful sandbox does not need to simulate your whole company.

It only needs to simulate the workflow developers are scared to test in production.

For a SaaS API, that might be:

customer → subscription → webhook → access change
Enter fullscreen mode Exit fullscreen mode

For an email API:

template → send → delivered/bounced webhook
Enter fullscreen mode Exit fullscreen mode

For a CRM API:

lead → contact → deal → status webhook
Enter fullscreen mode Exit fullscreen mode

For a CI API:

pipeline → workflow → job → failed/rerun
Enter fullscreen mode Exit fullscreen mode

The pattern is the same:

State has to move.

The next request has to see the previous request.

The webhook has to match the state change.

How I am thinking about this in FetchSandbox

This is one of the reasons I am building FetchSandbox around workflows, not just endpoints.

An OpenAPI spec can tell you:

POST /customers exists
Enter fullscreen mode Exit fullscreen mode

But an integration needs to know:

POST /customers
GET /customers/{id}
POST /subscriptions
webhook subscription.created
PATCH /subscriptions/{id}
webhook subscription.canceled
Enter fullscreen mode Exit fullscreen mode

That is the difference between an endpoint mock and an integration sandbox.

For small SaaS teams, I think this could be a lightweight way to give developers something close to a sandbox without building a full second production environment.

Start with one scary workflow.

Make it stateful.

Fire the webhook.

Let developers break it safely.

That is already much better than docs alone.

FetchSandbox is where I am testing this idea: turn an OpenAPI spec into a stateful sandbox with workflows developers can run before production.

Top comments (0)