Core concepts
Environments
Two realms, one set of paths, and a flag on every record telling you which one you're in.
One address, two realms
There is a sandbox and there is live. Which one you're in is decided by the credential you send, not the address you send it to. The same paths answer in both, so an integration you build against the sandbox keeps its URLs when you go live.
A sandbox key begins dw_test_. It's only ever a sandbox key: you can't present it against live data, and no endpoint on the self service path issues a live one.
Every record says two things about itself
Two fields appear on every record you get back, and they answer different questions.
| Field | Question |
|---|---|
livemode | Which realm is this record in. False in the sandbox, true in live |
mocked | Where did these numbers come from. True when they were mocked, false when they were computed for real |
Today every module resource in the sandbox is livemode: false, mocked: true. That won't always be so, and the two fields are not each other inverted: each record carries the answer that was true when it was made. All four combinations occur:
livemode | mocked | What it is |
|---|---|---|
| false | true | A sandbox record today |
| false | false | A sandbox record after that module goes live, computed on test data |
| true | false | A live record, computed |
| true | true | A live record whose numbers were mocked |
Write your code for the last row. When one module goes live and another doesn't, your live credential still reaches both, and mocked is the only thing that tells you which answer you're holding.
Don't read mocked as sandbox. Sandbox is the name of a realm, and livemode is the field that tells you which realm you're in.
What the sandbox does and does not do
Every documented endpoint answers with a realistic body, and a record you create is the record you get back. A new organisation starts with the records the reference shows, so a list is never empty and an identifier printed in these pages resolves to something real.
No money moves. No filing is made with any authority. No message reaches a worker. Nothing you do in the sandbox has an effect outside it, so try things.
What changes when a module goes live
Not the paths, and not the shapes. Once a module is live you send the same request and get the same response shape, computed for real rather than mocked, with mocked false and livemode true.
That's why you should build against the sandbox now rather than wait.