Testing an integration without leaving litter
There is no sandbox here. There is something better: a call that validates everything and creates nothing.
Start with the dry run
The validate endpoint takes the same body as create, applies the same schema and the same name rules, and returns every problem at once without writing anything. Most of an integration can be developed against it: field names, block shapes, error handling, the whole loop from a person’s answers to a valid request.
It is also the honest first call in production. A run that validates before creating turns a sequence of half-failures into one list, and it never burns an address on a body that was going to be rejected anyway.
- Develop against validate until the body is right and your error handling has been exercised.
- Then create one real page with a throwaway address and read it back as Markdown.
- Check the claim link opens and the page renders on a phone.
- Delete the page when you are done. Deletion removes the files and the statistics with it.
What to test that is easy to forget
- A taken name: expect a conflict with suggestions, and make sure you show them rather than choosing.
- A rate limit: expect a 429 with retryAfter, and make sure you wait rather than loop.
- A retry: send the same idempotency key twice and confirm you get one page, not two.
- A bad image URL: expect the page to be created anyway, with the failure reported in the warnings.
Litter, and what happens to it
Every test page you leave behind holds an address forever, because a deleted name stays parked so that old links never resolve to a stranger. That is the one cost of experimenting carelessly, and it falls on the next person who wanted that name.
There is a safety net: a page made by a program, never claimed and never visited, is unpublished after thirty days and deleted after sixty, and its name is released rather than parked. Rely on it for the runs you forgot, not for the ones you are running now.