Supercharge Your API Development with Utility Collections
The Postman Public API Network is well known for containing more than 120,000 collections and featuring some of the biggest brands on the planet. And while most of the collections exist to make it easier for developers to access the public APIs published by these companies, there are a few hidden gems in the API network that exist entirely to simplify and enhance the API workflow for developers using Postman. Here’s a handful of ones that I find especially helpful:
- Joyce Lin’s Public Workspace Linter examines the content of your public workspace to determine if it’s ready to be published publicly and gives you advice on how to improve.
- Nick Schott’s API First Workflow Patterns automation tool synchronizes your OpenAPI specification to Postman and automatically updates documentation, mock servers, and monitors within your workspace.
- Carson Hunter’s Workspace Cloning Utility will givesyou the ability to clone workspaces and even retain any forks on the collections.
- Allen Helton’s Contract Test Generator introspects your OpenAPI specification and instantly generates schema tests to ensure that your API implementation matches the specification that you’ve published.
Utility collections to the rescue
I call these types of collections “utility collections” because they don’t exist to represent an API or even an API workflow within an application. Instead, they exist to provide some utility that improves the way that you as a developer are utilizing the Postman API Platform.
Lots of developers are already creating and leveraging utility collections internally among and between their teams in order to do things like:
- Analyze tests for code coverage and produce a coverage report
- Lint OpenAPI specification files to make sure they meet minimum requirements
- Extend the contract testing approach for GraphQL, Protobuf, and even WSDL
- Find gaps in documentation and make these visible to workspace owners
- Fork common collections into new workspaces automatically so that developers can start working on them immediately
The amazing thing about these utility collections is that anyone has the ability to create them and publicize them using the Postman Public API Network.
Related: Use the Contract Testing Template
Have an idea for a utility collection?
A good utility collection should be simple to use and solve a single pain point for a user. If you’re considering building a utility collection, you should follow these four rules:
- Stay focused on a single purpose: Utility collections shouldn’t try to solve too many problems in one go. Like the example collections above, have a clear goal in mind to solve one problem. Make sure you constrain your scope to simplify something for your users.
- Require only a few easy-to-find parameters: The setup should be really easy for users. Asking users to copy Postman API keys, workspace IDs, and collection IDs is about as far as you want to take it. Opt for collection variables if you can, in order to keep things self-contained and avoid users from having to fork environments.
- Provide good documentation: Good documentation will ensure the user understands what the collection is aiming to achieve, how to get it working, and where to go for support. Before you publish your collection, make sure that your documentation is up to scratch so your users have a great experience.
- Respect the workspace: Unless it’s the expressed purpose, utility collections shouldn’t aim to modify anything within the workspace, instead opting either to simply advise the user of what has happened (through test results, visualizations, etc.) or through creating new collections in the workspace. Don’t modify any existing data if you don’t have to.
Share your work
Once you’ve completed building out your own utility collection, create a public workspace and publish it to the Postman Public API Network to share it with our community of more than 20 million users.
What do you think about this topic? Tell us in a comment below.