API workspaces provide a platform-driven approach to defining API operations, with a variety of building blocks that allow an organization to establish workspaces for each API, or suite of APIs, making artifacts, the lifecycle, and other elements of API operations more tangible. Providing a rich list of elements that can be applied in many different ways to provide private, team, partner, and public workspaces for producing and consuming APIs.
The common elements of a workspace help describe what it does and how it can be used by others, helping ensure that it is self-service and easy to put to work. Being consistent in how you name, describe, and make APIs workspace may not be evident with just a single workspace, but once you have tens, hundreds, and even thousands of workspace--the need becomes much more evident.
- Workspace Name - Having a consistent way for how workspaces are named, making it easy to discover and get up to speed on what is happening within a workspace.
- Workspace Summary - Offering a short and concise summary of what is happening in a workspace, providing an easy way to get up to speed with a light cognitive load.
- Workspace Overview - Providing a robust description of what is going on in a workspace, sharing as much detail about what is happening and why the workspace exists and helping provide the overview needed for new and existing team members.
- Workspace Visibility - Ensuring that the visibility of each workspace is deliberately kept private, made available to partners, and in some cases made accessible to public consumers, ensuring that privacy and security is the top priority. A little standardization at this level goes a long way when helping many different teams and roles make their way around operations. Workspaces when done right help reduce friction and lower the cognitive load when it comes to engaging with APIs across operations, so put the energy needed to craft the overview you need.
A workspace can contain one or many APIs, allowing teams to easily access the artifacts and other elements that support its operation. It is easy to just consider HTTP web APIs, but a workspace can include SOAP APIs, and is being evolved and iterated upon to consume GraphQL, gRPC, Websocket, and other APIs.
- Workspace OpenAPI API - Defining all of the HTTP APIs within a workspace, leveraging the OpenAPI specification as a contract, and providing a single location to go and find what is happening with each API being developed.
- Workspace SOAP API - Defining all of the SOAP APIs within a workspace, leveraging the WSDL specification as a contract, and providing a single location to go and find what is happening with each API being developed. HTTP web and SOAP APIs are front and center within workspaces, but GraphQL, gRPC, and Websockets are being invested in as well. This sets the stage for being able to access all APIs in use across the enterprise via simple-to-navigate, and easy-to-understand private, partner, and public workspaces.
There are a number of collections you can add to a workspace, providing each API with a suite of support elements that cover a wide variety of the API lifecycle. Collections provide the lifecycle view of each API, allowing you to define and automate documentation, mock servers, testing, and other ways in which an API is engaged with.
- Test Collection - Providing contract, performance, integration, security, and other types of tests, defined as the collection, which can be run manually, scheduled using monitors, as well as used in the CI/CD pipeline for each API.
- Workflow Collection - Defining workflows across many APIs and API paths provides a rich way to design and document common business workflows and practices, providing a specific sequence of API requests needed to accomplish a business objective, or just a subset of a larger API that meets the needs of a specific business sector, helping go beyond just a reference of everything an API does and getting closer to the business value.
- Reference Collections - Collections provide a rich way to define all of the operations available via an API, providing a single reference collection that describes the entire surface area of an API, offering a complete menu of what is possible.
- Onboarding Collections - When it comes to onboarding new consumers with an API or workspace, it helps to reduce the cognitive load by providing them with onboarding collections that only possess the API requests they will need to get started in their work.
- Capability Collections - Publishing single-use case collections that help teams execute common capabilities they need as part of their regular development, helping provide bite-size approaches to automation using APIs. It is easy to think of collections as a reflection of an entire API, but the. more granular you make them the. more opportunities you have for execution, engagement, and understanding how each collection is being used as part of your operations, helping shape and define what you do in a workspace.
Workspaces provide a place to organize definitions of each environment used for an API, providing access to development, staging, and production environments. Environments are a machine-readable representation of each environment that exists for an API.
- Development Environment - Having environments available for development environments, providing all of the variables and secrets needed to work on an API while it is being developed.
- Staging Environment - Having environments available for staging environments, providing all of the variables and secrets needed to work on an API while it is being tested and deployed
- Production Environment - Having environments available for production environments, providing all of the variables and secrets needed to work on an API while it is in operation.
- Sandbox Environment - Having environments dedicated to sandbox environments, making it easy for consumers to play with different business use cases with as little friction as possible. Environments help abstract away key/value pairs, secrets, tokens, and other information needed to work with APIs, helping keep separate from API definitions, as well as the collections, used to document, mock, test, and automate APIs across all their environments.
Monitors provide an automation opportunity across APIs, allowing different types of collections to be paired with environments, and then run on a schedule. Monitors can be run on a schedule, with the results of runs available as a report, and provide the ability to drill down into the details of each collection run.
- Test Automation - Monitors allow contract, integration, performance, security, and other types of tests to be run on a schedule, automating how and when tests are executed as part of regular team processes.
- Workflow Automation - You can use monitors to schedule workflow collections, going beyond test automation and executing specific business workflows, helping augment their capabilities and do more with fewer resources. Monitors complement collection runners, allowing teams to do more with fewer resources. Collections can be paired with different environments, have data injected as part of the run, and notifications and email alerts can be sent after a monitor is triggered, helping keep teams aware of what is happening.
Workspaces provide a unique opportunity to engage with consumers, offering a mix of ways to track signals across APIs and collections. Workspaces go well beyond the traditional developer portal, providing more of a glimpse into what is happening behind the curtain, and bringing producers and consumers together.
- Workspace Watches - The number of people who are watching a workspace, which is defined by the number in internal or external watches triggered for a workspace, offers a metric for understand the audience and reach a workspace and the APIs, collections, environments, mock servers, monitors, and other elements contained with in it possess.
- API Watches - The number of people who are watching each API, which is defined by the number of internal or external watches triggered for an API, offers a metric for understanding the audience and reach of each API deployed.
- Collection Watches - The number of people who are watching each collection is defined by the number of internal or external watches triggered for each test, mock, documentation, and other use cases, providing a metric for understanding the audience and reach of each stage of the API lifecycle.
- Collection Forks - The number of times a collection has been forked by users, offering a metric for understanding how many times the collection has been applied, but also. potentially how often contributions are made by the community. When thinking about engagement within workspaces, try to approach in as modular way as possible, considering the overall workspace engagement, but in a modular way by breaking up your APIs and the lifecycle using collections, offering you a granular look at watches and forks.
Workspaces have a handful of ways you can track the breadcrumbs of what is going on within the workspace across team members and the APIs being moved forward within each pace. When everything happens around an API in a workspace across teams, it becomes much easier to tune into what is happening.
- History - Having access to the history of requests and other activity associated with API operations, providing an accounting of what is happening from both producer or a consumer point of view, relying on logging, but making it much more usable as part of team or consumer working within any API workspace.
- Activity - The changes made to any aspect of operations by team members, provide observability into when APIs, mock servers, documentation, testing, monitors, and other critical elements of API operations are changed and configured-- helping give a log of everything that happens at the operational level.
It can be difficult to see APIs, let alone see what teams are up to when it comes to producing and consuming APIs, leaving a pretty big opportunity for workspaces to be used to aggregate everything in a single place. This helps the workspace become the institutional memory for your teams and operations when it comes to an API change.
Workspaces provide the ability to apply role-based access control at the workspace level, but also the APIs, collections, and environments contained within a workspace, helping manage what can be changed and can only be viewed, executed, or forked as part of the engagement.
- Workspace roles - You can assign three role types in Postman workspaces: Admin, Editor, and Viewer. Partner Workspaces offer an additional role type: Partner Lead. Admin - Can manage workspace resources and settings. Editor - Can create and edit workspace resources. Viewer - Can view, fork, and export workspace resources. Partner Lead (External, Enterprise plans only) - Can invite other partners from their organization to join a Partner Workspace. To learn more, see Partner roles.
- Collection roles - You can assign two role types in Postman collections: Editor and Viewer. Editor - Can edit collections directly. Viewer - Can view, fork, and export collections.
- Roles - You can assign two role types in Postman APIs: Editor and Viewer. Editor - Can edit APIs directly. Viewer - Can view and export APIs.
- Mock Server Roles - You can assign two role types for Postman mock servers: Editor and Viewer. Editor - Can edit and manage mock servers. Viewer - Can view mock servers and associated metadata.
- Environment roles - You can assign two role types for Postman environments: Editor and Viewer. Editor - Can edit and manage environments. Viewer - Can view and use environments.
- Monitor Roles - You can assign two role types for Postman Monitors: Editor and Viewer. Editor - Can view monitor metadata, metrics, jobs, and runs. Can run, update, delete, pause, and resume the monitor. Viewer - Can view monitor metadata, metrics, jobs, and runs. RBAC applied ad hoc is not effective as it is applied as part of a wider strategy using a known workspace checklist. RBAC provides a substantial opportunity for helping stabilize how teams are working, helping keep change from holding back the forward motion necessary to keep businesses competitive. API workspaces are often taken for granted by teams using Postman, but once they begin using in a collaborate way begin to see the potential of a more consistent approach to naming, defining, setting up, maintaining, and cleaning up workspaces. A little consistency goes a long way when it comes to streamlining enterprise operations by making everything you need to produce and consume APIs easily available within a single discoverable location.