DEV Community

Cover image for Postman Terms vs GitHub Terms
Johannes Nicolai for Postman

Posted on

Postman Terms vs GitHub Terms

I am an open source enthusiast who recently joined Postman and previously worked at GitHub. Many Postman concepts around organization, discovery, collaboration, users, and permissions are quite similar to GitHub’s, but they are referenced with different terms. We noticed in discussions with our community that it helped accelerate adoption of both platforms when we presented a short comparison of the concepts and their terms. This blog post builds on the first iterations of simple comparison tables in my Postman and GitHub profiles. Read on to learn more.

Organizing users

Postman team vs. GitHub Enterprise account

One of the key differences between Postman and GitHub is the concept of a team. In Postman, a team encompasses all users and workspaces within an entire company or larger business unit. It can potentially have thousands of workspaces and users (groups). GitHub uses the term "Enterprise Account" to refer to a similar concept, which encompasses all of the users and repositories within multiple organizations. If you are looking for a way to group a subset of users to form a “team of users” in Postman, have a look at user groups.

Postman user group vs. GitHub team(s)

In Postman, user groups are defined at the Postman account level and allow you to group users across multiple workspaces. User groups are a logical grouping of users based on a company's or organization’s needs. For instance, this grouping could be based on a people team, project, responsibility (i.e., an admin group), or some other logical organization of users.

In GitHub, teams are defined one level below (i.e., at the organization level) and govern access to the repositories of the organization to which they belong. GitHub teams can also be used to group people based on their responsibility or interest, but if you like to use teams across GitHub organizations, you need to duplicate them.

Postman team member vs. member of a GitHub Enterprise account/org member

A team member in Postman refers to a user who is part of a specific team within the organization. In GitHub, an equivalent concept is a member of an enterprise account or an organization member in a freestanding GitHub organization. A GitHub team member would only belong to one organization.

Postman Workspace Admin vs. GitHub org owner

A Workspace Admin in Postman has administrative privileges within a workspace. In GitHub, the equivalent role is an organization owner, who has full administrative control over the organization and its repositories.

Postman Super Admin vs. GitHub enterprise owner

In Postman, a Super Admin has the highest level of administrative privileges and can manage teams and workspaces across the organization. In GitHub, the equivalent role is an enterprise owner, who has full administrative control over the enterprise account.

Managing access

Postman workspace vs. GitHub orgs

Both Postman and GitHub provide features for organizing content and enabling collaboration. Workspaces in Postman are used to collaborate on collections, APIs, mock servers, monitors, environments, and Flows. In GitHub, organizations serve a similar purpose for managing repositories.

Postman public workspaces vs. GitHub orgs with public repositories

Postman allows you to create public workspaces that include publicly accessible content. Public Postman workspaces are comparable to GitHub organizations that contain only public repositories that are accessible to anyone.

Postman team workspaces vs. GitHub orgs with internal repositories

In Postman, team workspaces are accessible to any member of the same account or Postman team. In GitHub, this corresponds to internal repositories and standalone organizations that have their default access/base permissions set at least to “Read.” For Postman teams that represent multiple business units or larger parts of an organization, all elements within a team workspace are potentially visible to thousands of people. This is great from an InnerSource and company knowledge sharing perspective. In the cases where the “need to know” principle applies, consider using private workspaces and assign the groups of people that should have access.

Postman private workspaces vs. GitHub orgs with base permissions set to “None”

The word “private” in private workspaces does not imply that these workspaces can only be accessed by their creators (that’s what personal workspaces are for). It just means that not everybody in your Postman team will have read access by default (which is the case for team workspaces). You can use private workspaces to provide selective access to a group of people—either individually or by assigning Postman user groups to the workspace. You can also open the workspace up for entire business units.

In GitHub, most organizations within an enterprise team are configured similarly, with base permissions set to “None,” so that access rights are assigned by GitHub teams (which are similar to Postman user groups).

Postman Partner Workspaces vs. GitHub repositories with invited external collaborators

Postman allows you to create Partner Workspaces and share their contents with external collaborators outside the core team. In GitHub, you can invite external collaborators to specific repositories.

Postman personal workspaces vs. GitHub personal repositories

In Postman, users can create personal workspaces that can only be accessed by their creator and Super Admins of the same team. If a user leaves the enterprise team, they lose access to their personal workspaces, as well. Similarly, GitHub allows users to have personal repositories within their personal namespace that only they can access.

Postman collection access keys vs. GitHub Gists

Both GitHub and Postman provide methods to share access to source code or collections to anonymous users with a secret link. In GitHub, that functionality is called a secret gist. In Postman, it originally was possible to share private collections with the world via Collection JSON Links, which have been deprecated. Now, Postman users can use Collection Access Keys, which provide better control over the expiration date, as access gets revoked if the key’s creator loses access. Postman Enterprise teams can also deny public link creation completely and revoke any existing links.

Postman permissions vs. GitHub permissions

Postman Enterprise and GitHub both provide the ability to define permissions on multiple levels. Postman team roles on the highest level correspond with GitHub enterprise account-wide settings. Those roles and settings also define who can invite new users to the team or enterprise org, who can change the visibility of workspaces or repositories, and whether ordinary users can create public workspaces or repositories. Postman workspace roles compare best to GitHub organization default access permissions, and Postman permissions on individual collections, APIs, or mock servers (element-based roles) correspond to repository-specific permissions that a team or collaborator has on GitHub.

Managing collaboration and discovery

Postman fork vs. GitHub Fork

Postman allows you to fork collections, environments, and flows. It is possible to fork within the same workspace and into different workspaces. You can also have as many forks in the same workspace as you like, which makes fork-based collaboration easier. Furthermore, forks in Postman do not have to have the same visibility as the parent, and they will continue to exist if the parent gets deleted. You can keep your forks up-to-date by pulling changes from the base collection or environment, which is similar to how GitHub pull requests work.

Postman pull request vs. GitHub Pull request

Native pull requests in Postman require the reviewer to have at least “View” permissions in the fork, as the suggested changes are not created within the same workspace, as they are in GitHub. Postman pull requests also work for changes to environments. For API development, it is also possible to use native GitHub pull requests within Postman.

Postman comments vs. GitHub comments

In GitHub, you can comment on pull requests, individual source code lines in pull requests, and commits. Within Postman, you can comment on collections, requests, request parameters, folders, and individual lines in API definitions, test cases, and pre-request scripts. Both platforms support Markdown and tagging users to get their attention.

Postman tags vs. GitHub repository topics

In Postman, you can tag collections, APIs, and workspaces to make them easily discoverable within your workspace, your private API network, your team, or even the Public API Network. In GitHub, you can assign topics to repositories to make them more discoverable within the same organization or across all of GitHub.

Postman published documentation vs. GitHub Pages

Postman documentation can be published to a website hosted by Postman or to your own custom domain. Similarly, GitHub provides the ability to turn your repository content into a web page hosted on GitHub Pages with support for your custom domain, as well.

If you’d like to see what is possible with custom branding and domains, check out Imgur’s published Postman Collection.

“Run in Postman” button vs. GitHub Codespaces

If you have your own API or developer portal and you’d like to provide a lightweight way to test drive your APIs or source code in a live execution environment, you can generate a Markdown or HTML snippet with a “Run in Postman” button, or point to a GitHub Codespace of the corresponding GitHub repository.

PayPal’s developer portal includes a great example of how to use a “Run in Postman” button to let anybody try out your API within less than a minute without previous knowledge.

We love feedback!

We hope that these comparisons can help you to more easily adopt Postman and GitHub—and use them together. If you have any feedback or additional mapping suggestions, please open a pull request in our GitHub repository.

Top comments (1)

bitoiu profile image
Vitor Monteiro

Great article!!