Postman Simplified

A powerful npm package that automatically captures API requests from your Express backend and converts them into Postman Collections. Streamline your API testing workflow by automatically generating Postman collections from live API traffic.

Features

Automatic API Capture - Middleware that intercepts and logs all incoming API requests
Request Deduplication - Intelligently deduplicates requests based on method and path
Postman Export - Convert captured requests to standard Postman Collection format
CLI Tool - Easy-to-use command-line interface for exporting collections
Colored Output - User-friendly colored terminal output for better readability
Configurable - Customize output filename and file paths

Installation

npm install postman-simplified

Global CLI Installation

To use the postman-simplified CLI command globally:

npm install -g postman-simplified
# or
npm link

Quick Start

Step 1: Set Up Request Interceptor in Your Express Server

1. Module Type

import express from 'express';
import { requestInterceptor } from 'postman-simplified';

const app = express();

// Add the request interceptor middleware
app.use(express.json());
app.use(requestInterceptor());

// Your routes here
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

2. CommonJS

const express = require('express');
const { requestInterceptor } = require('postman-simplified');

const app = express();

// Add the request interceptor middleware
app.use(express.json());
app.use(requestInterceptor());

// Your routes here
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Step 2: Run Your Application

Make requests to your API using any HTTP client:

npm run dev
#or
npm run start

The interceptor will automatically capture all API requests and save them to api_history.json.

Step 3: Export to Postman Collection

Use the CLI to convert your captured API history to a Postman collection:

postman-simplified export api_history.json

Or specify a custom output filename:

postman-simplified export api_history.json -o my_collection.postman_json

This generates a Postman Collection file that you can import directly into Postman.

API Reference

requestInterceptor(options)

Express middleware that captures incoming API requests and logs them to a JSON file.

Parameters:

• options (Object, optional)
  • filePath (String): Path to save the API history. Default: 'api_history.json'

Returns: Express middleware function

Example:

import { requestInterceptor } from 'postman-simplified';

app.use(requestInterceptor({ filePath: 'my_api_history.json' }));

CLI Commands

export

Converts a captured API history JSON file to a Postman collection.

Usage:

postman-simplified export <input> -o [options]

Arguments:

• <input> - Path to the captured JSON file generated by the request interceptor

Options:

• -o, --output <filename> - Custom output filename (default: collection.postman_json)

Examples:

# Basic export
postman-simplified export api_history.json

# Export with custom output name
postman-simplified export api_history.json -o my_apis.postman_json

How It Works

1. Request Capture: The requestInterceptor middleware automatically captures every incoming HTTP request
2. Deduplication: Duplicate requests (same method and path) are intelligently deduplicated, keeping requests with request bodies when available
3. JSON Storage: All captured requests are stored in a JSON file (default: api_history.json)
4. Postman Conversion: The CLI tool reads the JSON file and converts it to Postman Collection v2.1.0 format
5. Import to Postman: The generated collection can be imported into Postman for testing

Example API History Format

[
  {
    "method": "GET",
    "path": "/api/users",
    "headers": {
      "content-type": "application/json",
      "user-agent": "Mozilla/5.0..."
    },
    "body": null,
    "time": "2024-05-02T10:30:00.000Z"
  },
  {
    "method": "POST",
    "path": "/api/users",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "time": "2024-05-02T10:31:00.000Z"
  }
]

Example Generated Postman Collection

The generated collection includes:

• Collection Info - Metadata and schema reference
• Requests - Organized with method and path as names
• Headers - All captured headers from original requests
• Body - Request payloads formatted as JSON
• URL Templates - Uses {{baseUrl}} variable for easy configuration

{
  "info": {
    "name": "Postman Simplified | Auto-Generated API Collection",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "GET /api/users",
      "request": {
        "method": "GET",
        "header": [...],
        "url": {
          "raw": "{{baseUrl}}/api/users",
          "host": ["{{baseUrl}}"],
          "path": ["api", "users"]
        }
      }
    }
  ]
}

Scripts

# Start development server with auto-reload
npm run dev

# Start production server
npm start

# Run tests
npm test

Dependencies

• express - Web framework for Node.js
• commander - CLI argument parsing
• chalk - Colored terminal output
• dotenv - Environment variable management
• nodemon - Development server with auto-reload

Requirements

• Node.js 16.0 or higher
• npm 7.0 or higher

Use Cases

• API Testing - Capture real API traffic and test against it in Postman
• Documentation - Generate API collections for team documentation
• Testing - Create comprehensive test suites from live API interactions
• API Development - Build collections while developing backend APIs
• Quality Assurance - Verify all API endpoints are working correctly

Troubleshooting

Issue: File not found error

Solution: Ensure the input file path is correct and the file exists:

postman-simplified export ./path/to/api_history.json

Issue: Empty or incomplete requests

Solution: The interceptor only captures requests made after the middleware is applied. Ensure you add the middleware before defining your routes.

Issue: GET requests not appearing in history

Solution: The interceptor skips duplicate GET requests by design. If you need to capture all GET requests, modify the deduplication logic in requestInterceptor.js.

Configuration

Custom History File Path

app.use(requestInterceptor({ filePath: './logs/my_history.json' }));

Project Structure

Backend to Postman Project
├── .gitignore   # Files to be ignored by git

├── .npmignore   # Files to be ignored by npm while publishing to npmjs

├── cli.js       # Terminal based options code - Chalk, Commander

├── index.js     # Entry Point
├── LICENSE      # Project License
├── package-lock.json
├── package.json
├── postman-mapper.js  # Converts to postman readable format

├── Readme.md  # Project Readme
├── requestInterceptor.js  # Middleware to be injected , handles the requests formatting to json

└── server.js  # Sample usage

Contributing

Contributions are welcome! Please feel free to submit a pull request.

License

MIT

Author

Pranava Pai N

• Github : Pranava Pai N

Support

For issues, feature requests, or questions, please create an issue in the repository.

---

Happy API Testing!