[tdeck]

I'd say the answer is no. People use OpenAPI because it produces a good result and fits conveniently into a company's workflow.

The most important aspects of good API documentation are

1) correctness,

2) thoughtful and complete examples, and

3) a clear explanation of the data model and state transitions.

These can be accomplished with any tool.

[hirokib]

Fair enough. In regards to point number 3, do you believe that sandbox APIs that persist objects like what Stripe does a must-have or a nice-to-have or somewhere in between?

[tdeck]

For me it depends on what the API does, and how much testing costs.

If it's something like Stripe (payments), Plaid (collects bank credentials), or Lob (sends physical mail), you definitely need a sandbox beyond the MVP stage. At one point we had a pre-launch payments API at Square and we provided partners with prepaid debit cards to test with, but that approach obviously doesn't scale well.

Another huge benefit of sandbox APIs is that people can use them for CI when testing their own integrations.

Still, when the cost of creating and manipulating objects in the production API is negligible I would say a sandbox is unnecessary.

As for how much persistence is needed in the sandbox, start with what is easiest to implement and gather feedback from your developers.

Be aware that developers often throw out ideas of API features that would be nice to have without much though about priority of effort involved. Sometimes they ask for something and then don't get around to updating their integration to take advantage of it.

[hirokib]

ya that's a fair point. Right now we just give canned responses but our API does have real world implications like Lob. Actual test kits get sent out. It's hard to balance essentially duplicating your prod environment for the sake of simulating things vs canned responses which just give you the different responses you'd expect. I guess the big downside is you don't get to test asynchronous changes to objects.