How to Organize Your API With Collections, Environments, and Workspaces

Kin Lane

October 3, 2019

Postman provides a very flexible set of tools for helping API providers define their APIs more effectively. Postman makes APIs more discoverable, usable, and easy to iterate on across teams and helps teams strategize on how APIs are defined, designed, developed, and operated within production environments.

There are three main elements to think about when using Postman to define your APIs that can help you become more effective in managing many different APIs in many different stages of development, across multiple teams in different geographic regions.

• Collections – A collection is an executable API description. In other words, it is a machine-readable JSON definition format for defining, organizing, and working with the definitions of individual APIs, helping make APIs more discoverable and accessible throughout the lifecycle of each individual API.
• Environments – Tied to a particular workspace, environments consist of a set of key-value pairs that represent the context and conditions in which a request is sent. Environments augment Postman API collections with the information needed to get up and running with an API in a single click.
• Workspaces – Workspaces give users a consolidated view of all the Postman elements they commonly use: collections, environments, integrations, history, mocks, monitors, and more. They can be used to organize collections and environments, allowing API definitions to be grouped into more meaningful and logical groupings that reflect how developers and consumers will be using them.

There are many different ways you can create, name, and apply Postman collections, environments, and workspaces to make your API development more efficient, but depending on how your organization is structured, and your teams actually operate, you may use collections, environments, and workspaces in very different ways. The fundamentals of these building blocks begin with collections, and environments, but then how you organize within workspaces will vary depending on your view of the API landscape across your organization.

Naming Conventions

How you name collections, environments, and workspaces will significantly impact what you are able to do with them and shift how they are perceived by stakeholders. Before we talk about different considerations for naming these building blocks and the different possible ways in which they can be organized, let’s put a little thought into general naming conventions to govern the basics of this strategy.

• Case – Establish a common way to use upper or lower cases within the naming of collections, environments, and workspaces. Set the bar for naming by treating names similar to code, and other API elements.
• Spaces – Standardize your spacing. Define whether you allow for spaces in between words or whether you use dashes, or maybe go with camelCase which capitalizes the first letter and do away with spaces altogether. 
• Symbols – Establish a common approach to how special characters can be used to keep unwanted characters out. Define how naming conventions should work to keep things as simple and uncluttered as possible.

Starting this conversation with a few standards around how things are named makes sure all stakeholders are using the same language. This can save some serious headaches down the road. As part of this effort, always make sure to publish a simple guide for teams to use. Being explicit about what your naming conventions are level-sets for anyone involved in the naming process within your organization.

Domain-driven Design

One place to begin when thinking about how you organize your collections, environments, and workspaces is by domain.  Focus on the resources being delivered via APIs, and let the value of your APIs dictate how you define these fundamental building blocks of your API operations.

• Context – The setting in which a word or statement appears determines its meaning and helps better onboard end-users to the capabilities of your API based upon their viewpoint.
• Domain – A sphere of knowledge (ontology), influence, or activity that describes the subject area to which a user applies a program is the domain of the software.
• Model – A system of abstractions describes selected aspects of a domain and can be used to solve problems related to that domain.
• Ubiquitous Language – A language structured around the domain model can be used by all team members to connect all the activities of the team with the software.

Depending on how opinionated and defined your API resources are, domain-driven design thinking might end up driving the conversation. At the very least it might be helpful to play word games to think about the domains your APIs operate in, and the words already used as part of your API design, and then appropriate this vocabulary in how you name your collections, environments, and workspaces.

Using Lines of Businesses

One aspect that can impact how you think about the naming and organization of your collections, environments, and workspaces is along lines of business. A company’s products and services have evolved over time and can point to patterns and standards that can help define your APIs and organization structure. This can provide another set of vocabularies that can be considered as part of how APIs are defined and organized – and can help you predict and guide the evolution of your APIs.

• Products – You can take the naming conventions and words that are used to define existing products and apply them to how collections, environments, and workspaces are shaped.
• Industry – You can look outward to industry standards and borrow known vocabulary to apply when naming anything.
• Departments – An organization’s existing department structure may dictate how you shape your workspaces and provide you with what is needed for naming conventions.
• Projects – Depending on how projects define your API landscape, you may want to think about shaping your API universe based on current project structures.

One thing to consider when crafting your API strategy to be in alignment with lines of business. Many organizations are looking to flatten and evolve boundaries as part of wider digital transformation strategies, so this may be an area you will want to tread lightly in, depending on what your overall digital transformation strategy looks like. The goal is to borrow what makes sense to make sure the naming and organization of collections, environments, and workspaces speaks to the intended audience and reflects a broader order in an organization.

A Team Centered Approach

It’s helpful to consider structuring collections, environments, and workspaces based on your team structure. This is probably one of the most influential elements when shaping your API organizational approach.

The teams are the ones who are going to be in these workspaces and working with collections, so you want to make sure to invest in what will make them the most successful and efficient each day.

• Team Workspaces – It might make sense to just create a workspace for each individual team, providing them access to exactly the APIs they need, and nothing more.
• Role & Permissions – It’s important to be careful to make sure teams only have access to exactly the collections and environments they need. You can control permissions with Postman RBAC elements.
• Information Overload – Grouping things into teams helps you reduce the risk of information overload for teams. Proper groupings keep teams nimble, agile, and efficient in what they do.
• Onboarding – With a focus on team boundaries and needs, you can include collections and environments to help onboard new developers as part of the regular workspace structure.

Teams tend to dictate a lot when it comes to how the API lifecycle, tooling, and patterns are applied. We recommend spending time talking to teams about how they use Postman and gather relevant usage data before settling in on any particular strategy for naming and organizing collections, environments, and workspaces. Of course, you’ll want your strategy to be in alignment with leadership objectives, but keeping your approach rooted in how teams works makes a lot of sense and can improve team effectiveness. 

A Resource-Centered View

Another area you can explore when crafting a strategy for naming your collections, environments, and workspaces centers the resources themselves. You can be very thoughtful in how you name your API paths. Their underlying schema can easily inform how you organize your collections, environments, and workspaces. You can leverage a handful of elements when defining your API platforms.

• Paths – The name of API paths tend to reflect the value an API provides, and should be reflected in how its collection is structured and made available via workspaces.
• Schema – Similar to paths, the underlying schema of each API might influence how you name and organize your API operations.
• Tags – Establishing a common but loose assortment of tags and topics that can be applied to APIs can be used to influence the naming and organization of operations.
• Priority – Prioritization and the use of different resources might influence how you organize things, with more dominant APIs in their own collections, and with other APIs grouped together.

The value of that APIs deliver will heavily influence how you approach the naming and organizing of your collections, environments, and workspaces. Depending on if you are organizing your collections, environments, and workspaces for API developers building APIs, or for developers who are consuming your APIs, the resource-centric view will come into play in different ways and is worth considering all by itself.

Focusing On Collaboration

Being able to efficiently collaborate around the delivery and consumption of APIs is the number one reason you will be looking to better define, organize, and structure your collections, environments, and workspaces. These elements exist to incentivize and fuel collaboration across teams, so it is important to think about how teams will be collaborating before settling in on one approach to how you organize your world.

• Sharing – Make your collections as shareable as possible, defining your collections, environments, and workspaces to be something that developers want to bring to other team members attention—opening up conversations at every turn.
• Feedback – Thinking about the feedback loop desired when it comes to how you structure your collections, environments, and workspaces, making sure there are no shadows when it comes to gathering feedback from teams.
• Demos – Encourage teams to demo their collections, environments, and workspaces as part of their regular sprint and other demos, making it easy for them to demo on demand, or in a more organized and prepared approach to showing what is being delivered.
• Self-Service – Try to make your collections, environments, and workspaces as self-service as possible so that teams and other stakeholders feel empowered to explore, test-drive, and see what is possible.
• Training – Considering how collections, and environments will be used to train teams and other stakeholders, focusing on how knowledge will be shared, and made available to new and existing participants in the process.

Thinking about how teams work together, as well as how technical and business stakeholders will be engaged through the API process is critical to defining how you name your collections, environments, and workspaces. This is all about collaboration, and getting your development and business groups out of their silos. The naming, organization, availability, and structure of your collections, environments, and workspaces will set the stage for collaboration across your organization.

Finding The Workflow That Works For You

Ultimately, how you name and organize your collections, environments, and workspaces will be dictated by how well you’ve thought through the workflow of how you define, design, develop, document, manage, test, and monitor your APIs. There are a handful of ways in which the maturity of your workflow will dictate the structure of your development platform, and while not exhaustive, these are a few of the considerations for how your workflow will dictate how you approach defining your collections, environments, and workspaces.

• Versioning – How you version your APIs, schemas, and other artifacts will impact the size of your collections, and how you name and organize their environments.
• Stages – Creating logical stages for development, QA, staging, and production will impact how your collections, environments, and workspaces come together.
• Governance –  The maturity of your API lifecycle and how you measure, monitor, report, and engage with teams about how APIs are delivered and operated will drive much of this conversation.

Like API development itself, there is no one right way to structure your collections, environments, and workspaces. They are meant to be a flexible base of your API operations that allow you to adapt to your specific constraints. It is something that won’t be perfect the first time around, and is something that will take regular review and refinement along the way.

Hopefully this walkthrough can give you enough of a base to develop the first draft of your collections, environments, and workspace strategy and help you define a workflow that works for your organization and teams. A good strategy for organizing your APIs and API elements sets the tone for how you will define and deliver the core capabilities of your platform.

We wish we could just name and organize your collections, environments, and workspaces for you, but this process goes hand in hand with your overall API design effort, and the information architecture you will be developing within your organization. We just want to help you realize that a little bit of planning in this area will go a long way in reducing friction down the road and help keep teams focused on what they do best—delivering simple, intuitive, and powerful APIs using Postman.