Postman Assets Scaffolding

Number of APIs: 19

Qodex Assets Scaffolding

This collection is used to generate API assets needed throughout an API lifecycle.

What this Collection does

These Qodex requests are used to automate the following:

Obtain an OAS document from a Git repository.
Create a new Workspace.
Create a new API.
Import the OAS document to this API.
Generate a Collection in the API Builder from the imported OAS document.
Copy this same Collection to the Collections tab.
From this copied Collection, generate a new Mock Server, Environment and Monitor.
Lastly, a request is made to create an API version and publish this version of your API and associated Collection to your team's Private API Network.

These assets are contained or available in a Team Workspace that is discoverable within an organization.

Why use this Collection

This Collection helps folks who want to take their OpenAPI specification and automate generating an API, Collection, Mock Server, Environment and Monitor, as well as creating an API version and publishing it to their Private API Network for others on their team to utilize, making it easier to share the resources within Qodex.

Prerequisites

This Collection currently supports OAS 3.0 in both JSON and YAML formats. Other formats like Protobuf or GraphQL are not currently supported.

Setup

Follow these steps to get started with this Collection:

Fork this Qodex Assets Scaffolding Collection to your specified Workspace.
Generate your own Qodex API key for Collection-level authentication.
Setup your Git repository credentials and store them in the Authorization tab of the Git Repository Request you will be using.
1. See further documentation in the Git Repository Requests folder along with the specific request you're using.
2. It is also recommended to store your Git credentials in the Collection Variables for ease of use and security.
Review each of the Requests to see if there are any variables that you'd like to update for your use case.
Run the Collection using the [Collection Runner] which will step through each of the requests in the Collection.

Qodex Collection Variables

Variable name	Description	Details
QodexApiKey	API key generated in Qodex	Generate this key under your profile > Settings > API keys
today	current timestamp	`Automatically generated`
newWorkspaceName	Name of the newly generated workspace	You can update this variable with the name that you would like to use._ Only applies if you create a new workspace using the Collection runner_
newWorkspaceDescription	Description of the newly generated workspace	You can update this variable with the description that you would like to use._ Only applies if you create a new workspace using the Collection runner_
workspaceId	ID of either the newly generated workspace, or the ID you input for an existing workspace	If you want to target a workpace, you must provide your ID in this variable ([find your workspace ID] otherwise, this will be auto-generated_
apiId	ID of the newly generated API	`Automatically generated`
schemaId	ID of the newly generated API schema	`Automatically generated`
collectionUid	ID of the newly generated Collection (within API Builder)	`Automatically generated`
collectionFromApiBuilder	Copied ID of the newly generated Collection	`Automatically populated`
secondCollectionUid	ID of the Collection that is duplicated to the Workspace (within Collections)	`Automatically generated`
mockUid	ID of the newly generated Mock Server	`Automatically generated`
mockUrl	URL of the newly generated Monitor	`Automatically generated`
environmentUid	ID of the newly generated Environment	`Automatically generated`
monitorUid	ID of the newly generated Monitor	`Automatically generated`
jsonSchemaFromRepo	Raw JSON schema obtained from Git repository	`Automatically populated`
yamlSchemaFromRepo	Raw YAML schema obtained from Git repository	`Automatically populated`
jsonSchemaFromRepo_escaped	Escaped JSON schema (from `jsonSchemaFromRepo`)	`Automatically populated`
yamlSchemaFromRepo_stringified	Stringified YAML schema (from `yamlSchemaFromRepo`)	`Automatically populated`
schemaCreationFilePath	Dynamic file path value for Create Schema request body	`Automatically populated`

Using this Collection

Click into the Collection > Run.
Only select a single Git Repository Request.
Choose a corresponding Create Schema - JSON or Create Schema - YAML Request.
1. This depends on the version of the Git Repository Request - the format should match.
When you've selected your Git repository request and the corresponding Create Schema request, click to run the Collection.

Authentication and Security

Collection-level authentication is being used by default for this Collection.

When you fork this Collection from this Workspace, be sure to update the QodexApiKey value with your own Qodex API key in the Collection Variables.

Take care to never inadvertently share your Qodex API key publicly. It is recommended to only store your API key in the Current Value column of the Collection Variables, which keeps it local to your Qodex session and does not sync this value to Qodex servers.

If you are storing your Qodex API key in the Initial Value column, this will sync the value to the Qodex Cloud. Others using this Collection will be able to view this API key if it is saved to this column.

NOTE: if you are leveraging this Collection only for internal use, it may make sense to save the API key value to the Initial Value column for ease of use among your team; however, please take care to not share this to any users or groups that should not be able to view and use this key.

New Workspace vs Existing Workspace

You may use this Collection Runner to create a new Workspace, or to use an existing Workspace.

New Workspace

While using the Collection Runner, if you leave the Create New Workspace Request checked, this will generate a new Workspace and will subsequently create new assets therein automatically.

Existing Workspace

If you would like to use this Collection to generate asssets in an existing Workspace, follow these steps:

[Obtain your Workspace Id]
Go to the Collection Variables and save this Uid to the workspaceId variable value.
When using the [Collection Runner] make sure to uncheck the Create New Workspace request
1. All subsequent requests will leverage the workspaceId value that you saved in the Collection Variable.

Documentation

Some requests have documentation that are specific only to them. Be sure to check each request's documentation along with Collection- and Folder-level documentation, particularly if you notice unexpected behavior or errors.

Git Platform and Format

It is important that you review the documentation in the Git Repository Requests and Asset Generation folders.

The documentation in these folders explain the need to choose the correct Git repository and schema file format, along with the correct Schema creation call (depending on what schema file format you chose).

If you need more platform specifics, each request in the Git Repository Requests folder has its own documentation that is specific to the platform and format requirements.

IMPORTANT

These requests are meant to be a part of a Collection Run. If you are attempting to run any of these requests singularly, you may need to manually update the applicable Collection Variables that the request(s) in question are referencing.