A Postman fork is essentially a personal copy of a shared Postman collection that you can modify independently, with a built-in mechanism to propose those changes back to the original.
Let’s see this in action. Imagine you’re working on an API with a team, and the API’s Postman collection is stored in a central workspace.
Here’s a simplified version of a collection in Postman:
{
"info": {
"_postman_id": "a1b2c3d4-e5f6-7890-1234-abcdef123456",
"name": "My Awesome API",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Get Users",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/users",
"host": [
"{{baseUrl}}"
],
"path": [
"users"
]
}
},
"response": []
},
{
"name": "Create User",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\"\n}"
},
"url": {
"raw": "{{baseUrl}}/users",
"host": [
"{{baseUrl}}"
],
"path": [
"users"
]
}
},
"response": []
}
]
}
In your Postman workspace, you’d see this collection. If you need to add a new endpoint, say GET /users/:id, you can’t just edit the original collection directly if you don’t have write permissions or if you want to experiment without affecting others. This is where forking comes in.
You click the "Fork" button on the collection. Postman asks you where to save your fork. You can create a new workspace or save it in your personal workspace. Let’s say you fork it into your personal workspace. Now you have your own copy, perfectly synchronized up to that point with the original.
You can now edit your forked collection: add that GET /users/:id request. You might also want to add some new environment variables or update existing ones.
Once you’re happy with your changes, you "Commit" them to your fork. Postman prompts you for a commit message, just like Git. Now, your fork has diverged from the original collection.
The real power is in proposing these changes back. You can create a "Pull Request" from your fork to the original collection. This is where the collaboration happens. The owner of the original collection (or anyone with merge permissions) will see your proposed changes. They can review your new GET /users/:id request, see any changes to variables, and decide whether to "Merge" your changes into the main collection. If they merge it, your new endpoint becomes part of the official API collection for everyone.
This process mirrors Git’s workflow:
- Fork: Create your own branch (your forked collection).
- Clone: Postman handles this by giving you a copy.
- Branch: Implicitly done when you fork.
- Commit: Saving your changes within your fork.
- Pull Request: Proposing your changes to the upstream (the original collection).
- Merge: Integrating your changes into the main branch.
This solves the problem of managing API documentation and test collections in a team environment. Without it, you’d have multiple people editing a single file, leading to chaos, or worse, using separate, unmanaged copies. Forcing everyone to use a shared workspace and fork/pull request model ensures that changes are reviewed and integrated, maintaining a single source of truth for your API’s definition and tests. It’s like having version control for your API’s contract and its associated tests.
The "Sync" status in Postman is crucial here. When you fork, it’s initially "Synced." As you make changes, it becomes "Unsynced." After you commit, your fork might still be "Unsynced" from the original if the original has been updated by someone else since you forked. You can then choose to "Sync" your fork with the latest changes from the original collection, which will pull those updates into your forked copy, and you can resolve any conflicts if you’ve both modified the same parts.
The next step in mastering Postman collaboration is understanding how to manage environments and mock servers alongside your forked collections.