Pmsync NPM | npm.io

PostmanSync

Overview

PostmanSync is a utility designed to maintain continuous synchronization between a user's Postman collection and the schema definition file located in their code repository. Additionally, it facilitates automatically publishing updated API versions to the Postman API Network.

Installation

To install PostmanSync:

Ensure you have Node.js installed.

npm install pmsync

Setup

Here are the basic steps for setting up your repository and codebase with an API in Postman:

Initialize PostmanSync

1. In your repo, create a new branch called pmsync-setup:

$ git branch pmsync-setup

2. If you haven't done so already, install PostmanSync:

$ npm install pmsync

3. Install the configuration file in your repo (use the workspace ID where the API should be created):

$ pmsync config -w myWorkspaceId

4. Create an .env in your root directory and paste your Postman API token:

POSTMAN_API_KEY = "YOUR-POSTMAN-API-TOKEN"

Create a new Postman API and collection

6. Create a new API and embedded collection in your Postman workspace

$ pmsync create-api -n "My API" -d "Short summary" -s path/to/your-schema-file.json

6. Commit and push changes to your GitHub repo

$ git add .
$ git commit -m "pmsync installed and configured" --no-verify
$ git push origin pmsync-setup

Create the GitHub integration

7. Follow the link in the terminal to navigate to the API in Postman and connect it to your GitHub repository as follows:

Select your Github organization and Repository
Select the pmsync-setup branch as the Initial branch
Select the schema file in your repo for API schema file
Skip Collection directory unless you want to specify a path other than the default
Click Connect Repository
Commit and push from Postman to the pmsync-setup branch in your GitHub repository
- Select the source control icon in the right sidebar
- Enter a commit message and select Commit and Push.

8. Pull changes into your local pmsync-setup branch.

$ git pull origin pmsync-setup

Setup Hooks and Workflows

9. Add the precommit hook

$ pmsync hook

Now whenever your schema file changes, your collection file will automatically update on the next commit.

10. If you want to setup CICD publishing to the Private API Network, install the github workflows

$ pmsync workflows

You can map branch names to API version names within the apiVersionNames key of your pmsync.config.json file

  "apiVersionNames": [
    {
      "branch": "main",
      "version": "PROD"
    },
    {
      "branch": "develop",
      "version": "NON-PROD"
    }
  ]

When you merge into one of the mapped branches, a version with the configured name will automatically be created/updated, and your API will be published to the Private API Network. Additionally, you can publish from a configured branch by running the workflow manually from your Github repo's Actions page.

Configuration

PostmanSync uses the config file located at pmsync.config.json to manage various settings:

baseUrl: The base URL used for creating the collection. Include curly brackets in the value if this is a Postman variable.
bearerToken: The bearer token for authentication when creating the collection. Include curly brackets in the value if this is a Postman variable.
workspaceId: The ID of the Postman workspace where the API is located.
apiId: The ID assigned to the API within Postman.
variablesToConvert: An array of objects defining fields in collection request bodies where values should be replaced. Typically used for Postman variables, but applicable to any string. Each object follows the format: {"requestBodyField": "valueToInsert"}.
networkFolderId: The ID of the folder in the Postman network where API versions should be published.
networkFolderName: The name of the folder in the Postman network for publishing API versions. If networkFolderId is not provided, PostmanSync will search for a folder with this name when publishing a new version.
apiVersionNames: An array of objects linking code repository branches to Postman version names. Each object must include:
- branch: The name of the repository branch.
- version: The corresponding version name in Postman.
postmanSubdomain: The custom subdomain used with Postman (e.g., my-organization.postman.co). Set this to my-organization.

Commands

Here are the primary commands available in PostmanSync:

Initialization

pmsync init [options]

Options

* If none of -c, -h, and -g are provided, all three of these initializations will take place.

-c, --config: Initiates the creation of a configuration file *
- -w, --workspace-id <workspaceId>: Sets the Postman workspace ID.
- -vp, --variablePrefix: Specifies a prefix to affix to the {{baseUrl}} and {{bearerToken}} Postman variables (Providing service will result in creating {{serviceBaseUrl}} and {{serviceBearerToken}} variables).
- -u, --base-url [baseUrl]: Manually defines the baseURL for the API's embedded collecetion.
- -b, --bearer-token [bearerToken]: Manually defines the bearer token for the API's embedded collecetion.
-h, --hook: Installs a pre-commit hook to ensure your Postman collections and environments are synchronized before each commit *
-g, --github-workflows: Generates GitHub workflows for continuous integration *

Description

Establishes the necessary configurations, installs hooks, and generates GitHub workflows to automate the synchronization process.

Examples

# Initialize with default settings
pmsync init

# Initialize with a variable prefix and workspace ID
pmsync init -vp service -w myw0rkspace-466c-aae3-29ae0602550b

Install Pre-commit Hook

pmsync hook

Description

Installs a pre-commit hook into your Git repository via Husky, ensuring that your Postman collections and environments are automatically checked and synchronized before each commit.

Install GitHub Workflows

pmsync workflows

Installs GitHub workflows from PostmanSync templates to your .github/workflows directory, creating necessary folders if they don't exist. Existing workflow files won't be overwritten.

Usage

pmsync workflows

Sync Postman Collection with Schema

pmsync sync [options]

Options

-s, --schema-file-path [schemaFilePath]: Path to the OpenAPI schema file.
-u, --base-url <url>: Base URL for the API.
-bt, --bearer-token <baseUrl>: Bearer token for authorization.
-c, --collection-file-path [collectionFilePath]: Path to the Postman collection file (defaults to the collection file path stored in the .postman config file).

Description

Synchronizes a Postman collection with an OpenAPI schema, updating the collection file and applying authentication details. If the collection file doesn't exist, it will be created.

Example

# Sync Postman collection with OpenAPI schema
pmsync sync -s postman/schemas/swagger-spec.json -c "postman/collection/My Collection.json" -u "{{serviceBaseUrl}}" -bt "{{serviceToken}}"

Create a New API

Requires a Postman token to be either stored as an environment variable POSTMAN_API_KEY or supplied with the -k flag

pmsync create-api [options]

Options

-s, --schema-file-path [schemaFilePath]: File path to API schema.
-n, --name <name>: API name (required).
-d, --description [description]: API short description/summary.
-k, --api-key [apiKey]: API Key for Postman.
--no-collection: Create API only, without adding a collection.

Description

Creates a new API in Postman. By default, it also adds a collection to the API based on the schema provided with the -f flag (use the --no-collection flag if you want to create the API without a collection). Upon successful creation, the command prints the API name, ID, and a URL to connect your GitHub repository to the API in Postman.

Example

# Create a new API with name, summary, and description
pmsync create-api -n "Burger Service" -d "Service API for hamburger ingredients" -s postman/schemas/my-swagger-file.json

# Create a new API without schema and collection
pmsync create-api -n "Burger Service" -x

Create or Update an API Version

Requires a Postman token to be either stored as an environment variable POSTMAN_API_KEY or supplied with the -k flag

pmsync version [options]

Options

-i, --versionId [versionId]: If provided, updates an existing API version.
-a, --api-id [apiId]: Postman API ID (required if versionId is provided).
-n, --name [versionName]: Version name (required for new version).
-b, --branch [branchName]: GitHub branch name (required for new version).
-rn, --release-notes [releaseNotes]: Release notes.
-k, --api-key [apiKey]: API Key for Postman.

Description

Creates a new API version or updates an existing one in Postman. For a new version, name and branch are required. To update, provide the versionId.

Example

# Create a new API version
pmsync version -n NON-PROD -b develop -k PMAK-12345-abcdef-67890

# Update an existing API version
pmsync version -i myap1v3r-si0n-4373-a04f-c19d1d057474 -rn "Updated endpoints"

Publish API Version from Branch

Requires a Postman token to be either stored as an environment variable POSTMAN_API_KEY or supplied with the -k flag

pmsync publish [options]

Options

-a, --api-id [apiId]: Postman API ID.
-rn, --release-notes [releaseNotes]: Release notes for the API version.
-b, --branch <branch>: GitHub branch name.
-n, --name [versionName]: API version name (overrides version name configured with branch in pmsync.config.json).
-k, --api-key [apiKey]: API Key for Postman.

Description

Publishes an API version to the Postman Private API Network based on the GitHub branch. The version name will equal the name set in the apiVersionNames array of pmsync.config.json for the branch (unless provided explicitly with the -n option). If a version with the same name already exists, it will be replaced.

Example

# Publish API version using version name configured for branch
pmsync publish -a myapiId-1234-abcd-5678-efghijklmnop -b main

# Publish API version using a custom version name
pmsync publish -a myapiId-1234-abcd-5678-efghijklmnop -rn " -b mvp-spec-branch -n "0.1"