Introducing Postman Assets Scaffolding to automatically build Postman assets

The Postman Team

June 14, 2023

Today, we’re announcing a new tool known as Postman Assets Scaffolding (PAS), which is available in the Postman Public Workspace. This exciting collection helps users leverage OpenAPI Specifications (OAS3) to automate the process of creating API assets (Postman workspaces, APIs and schemas, collections, mock servers, environments, and monitors). Along with automating the creation of these resources, it also creates a new API version and publishes it to your Private API Network, making it easier to share these resources with your team directly within the Postman API Platform.

Why was Postman Assets Scaffolding  created?

PAS was created due to a customer use case in which they wanted to automate resource creation in order to deliver a more consistent user experience to their API consumers, thus accelerating the critical time to first API call (TTFC).

The TTFC metric is a great way to measure just how easily your consumers can find your API and begin using it. By measuring TTFC, you can ensure that your APIs are getting used consistently, while observing any potential issues with its adoption. The metric can be measured via collecting feedback from your API consumers or by measuring the time from which API credentials are granted to the time a first successful API call is made.

Why use this new tool?

Postman Assets Scaffolding can be particularly useful for API producers who need to frequently create API resources from any OAS3 specification and would like to automate the process to save time. It will also provide a more consistent experience to help consumers quickly get started with using an API; upon creation, these resources will directly reflect the OAS specification used, as opposed to having been manually created or imported from other sources, etc., ensuring that you have consistency in your Postman assets.

Please note that PAS is not bound to any specific workflow. It’s possible that you need all assets created, or only need a portion of the available assets created. If you have a specific flow which this utility may help, feel free to give it a try!

PAS can help you do things like:

• Generate a new API and collection, and then publish to your Private API Network
• Automate the creation of a new mock server from a new collection based on your API specification

To use this new tool for a more specific creation flow, all you need to do is select the necessary API requests, update all necessary variables that will be used in the selected requests, ensure your authentication data is in place, run the collection, and allow Postman Assets Scaffolding to do the rest!

Supported API formats

Please note that PAS currently supports the OAS 3.0 specification in both JSON and YAML formats. Other specifications like OAS2/Swagger, Protobuf, or GraphQL are not currently supported but may be added in the future. Feel free to also fork this collection, improve upon it, and submit a pull request back to us.

Git resources

The expected source of your OAS file is a Git repository (Git platforms currently supported are Azure DevOps, BitBucket, GitHub, and GitLab). Once the OAS3 file is obtained from your specified Git repository, the other assets can be generated automatically.

Authentication

OAuth 2.0 is used to authenticate and authorize requests from Postman to your Git repository. A Postman API key is used to authenticate API calls to Postman.

How to get started

1. Click the Run in Postman button above and follow the prompts to either view or fork the collection into your own workspace.
2. Add a Postman API key (or reference a previously created API key) for this collection within the workspace to which you’ve forked it.
3. Set up your Git repository credentials and store them in the Authorization tab of the Git repository request that you will be using. Each of the Git repository folders in the collection has instructions on how you can generate your credentials.
   1. It is also recommended to store your Git credentials in the collection variables for ease of use and security.
4. Review each of the requests and the documentation at the request level to see if there are any needed updates.
5. Run the collection using the Collection Runner, which will step through each of the requests in the collection.
   1. If you’d like to choose which requests to run, you can simply keep those requests checked in the Collection Runner. However, please note that you may have to update any associated collection variables that are used in the request.

GitLab example

First, navigate to the documentation in the specific request under the Git Repository Requests > GitLab folder. Next, choose the request based on your OAS3 file format (YAML vs JSON). Then, follow the instructions to generate a valid access token.

You will need to generate your platform-specific client information (e.g., Client ID, Client Secret) within the appropriate platform prior to generating your access token in Postman.

Once you’ve populated the required authentication information, it’s time to run the collection.

We are here to help

Learning any new tool can be intimidating or confusing. Please let us know in the comments below if there are any questions, ideas for updates, or issues concerning Postman Assets Scaffolding that you’ve encountered, and we’d be happy to help!

This post is by Postman Technical Enablement Architects Michael Lanius and Salomé K. Braganza-Gallagher.