Using Postman Workspaces and GitHub Repositories Together

05-01-2020

I find that it helps to have defined boundaries for your APIs. If you have the resources and interest I recommend studying subjects like domain driven design. Investment in properly defining the boundaries of your organization and lines of business is a very worthy endeavor—if you have the time. However, if you already have a lot on your plate, and are just looking for incremental changes that can help make your life easier when it comes to the API sprawl we’ve introduced into our worlds, I recommend just spending a few moments thinking about how you can better use Postman workspaces to dive and conquer your API landscape.

I have begun using Postman workspaces in similar ways that I use GitHub repositories. The GitHub repository has long represented a unit of API value in my world, but with the introduction of GitHub two-way sync into Postman I now have a one for one matchup between workspace and repository when it comes to moving each API forward. For my API-first e-commerce reference implementation Union Fashion I am currently developing five separate APIs, which each have their own Postman workspace and GitHub repository pairing.

  • Products - (Workspace) (Repo) (Docs) - Defining all of the products that Union Fashion offers.
  • Orders - (Workspace) (Repo) (Docs) - Allows for the ordering of Union Fashion products online.
  • Baskets - (Workspace) (Repo) (Docs) - Allows for the ordering of Union Fashion products online.
  • Users - (Workspace) (Repo) (Docs) - Defines users who engage with the Union Fashion platform.
  • Search - (Workspace) (Repo) (Docs) - Provides a universal search for products, orders, and users.

Postman workspaces and GitHub repositories accomplish many overlapping concerns along the API life cycle, however I am finding that Postman workspaces are better suited for establishing a tighter team level definition of who should have access and voice in moving an API forward, but GitHub is better for a more organizational-wide, or a public level of engagement. With both workspaces containing many of the same artifacts, but they will be evolved and consumed in different ways within a Postman workspace, or GitHub repository. Making for a pretty powerful Venn diagram when it comes how I move APIs forward as part of this project.

There is a natural synergy between Postman workspaces and GitHub repositories for me. Postman workspaces very much reflect the organization and tighter knit collaboration I need for each individual API, and the GitHub repositories reflect that next outward wave of engagement via a private or public GitHub repository. I can sync my artifacts between Postman and GitHub, and use both platforms APIs to orchestrate and automate the evolution of each individual API. Using Postman workspaces and GitHub repositories in tandem is allowing me to be a little more organized about how I roll out my APIs, and helps me establish relevant bounded contexts to any of the API resources I’m pushing forward.