Why it matters for agencies
Developers use an API client every day to try an endpoint before writing code against it. The trouble starts when requests, tokens and environments live on one person's machine and have to be re-created by everyone else.
How to do it or work it out
Save requests in collections, use variables for things that change between environments (such as the base address and tokens), and keep secrets out of the saved request.
Share the collection so the whole team works from the same requests, and add tests that check the status and shape of responses so a change that breaks an endpoint is noticed.
Keep one collection per API and one environment per stage. Name requests after what they do, save examples of real responses, and use those examples to document the API as you go.
A worked example
A team keeps a collection for a client's API. A variable holds the base address, with one environment for staging and one for production. A new developer opens the shared workspace, picks the staging environment and sends the first request without asking anyone for a file. When the client changes an endpoint, the developer updates the shared request once and everyone sees the new version. A teammate who needs the old one can restore it from version history.
Common mistakes
- Pasting tokens into saved requests. They end up in shared collections, so keep secrets in environment variables.
- Testing only the happy path. Also try a missing field, a wrong token and an empty list, because those are the cases clients hit.
- Keeping collections in personal accounts. When someone leaves, the only copy of the requests goes with them.