postmanlabs/postman-collection-transformer

Perform rapid conversion and validation of JSON structure between Postman Collection Format v1 and v2.

Postman Collection Transformer

Perform rapid conversion of JSON structure between Postman Collection Format v1 and v2.

The formats are documented at https://schema.postman.com

Installation

For CLI usage:

$ npm install -g postman-collection-transformer

As a library:

$ npm install --save postman-collection-transformer

Usage

Converting Entire Collections

The transformer provides a Command line API to convert collections.

Example:

$ postman-collection-transformer convert \
    --input ./v1-collection.json \
    --input-version 2.0.0 \
    --output ./v2-collection.json \
    --output-version 1.0.0 \
    --pretty \
    --overwrite

All options:

$ postman-collection-transformer convert -h

  Usage: convert [options]

  Convert Postman Collection from one format to another

  Options:

    -h, --help                      output usage information
    -i, --input <path>              path to the input postman collection file
    -j, --input-version [version]   the version of the input collection format standard (v1 or v2)
    -o, --output <path>             target file path where the converted collection will be written
    -p, --output-version [version]  required version to which the collection is needed to be converted to
    -P, --pretty                    Pretty print the output
    --retain-ids                    Retain the request and folder IDs during conversion (collection ID is always retained)
    -w, --overwrite                 Overwrite the output file if it exists

If you'd rather use the transformer as a library:

    var transformer = require('postman-collection-transformer'),
        collection = require('./path/to/collection.json'),
        inspect = require('util').inspect,

        options = {
            inputVersion: '1.0.0',
            outputVersion: '2.0.0',
            retainIds: true  // the transformer strips request-ids etc by default.
        };

    transformer.convert(collection, options, function (error, result) {
        if (error) {
            return console.error(error);
        }

        // result <== the converted collection as a raw Javascript object
        console.log(inspect(result, {colors: true, depth: 10000}));
    });

Converting Individual Requests

The transformer also allows you to convert individual requests (only supported when used as a library):

Example

    var transformer = require('postman-collection-transformer'),

        objectToConvert = { /* A valid collection v1 Request or a collection v2 Item */ },

        options = {
            inputVersion: '1.0.0',
            outputVersion: '2.0.0',
            retainIds: true  // the transformer strips request-ids etc by default.
        };

    transformer.convertSingle(objectToConvert, options, function (err, converted) {
        console.log(converted);
    });

Converting Individual Responses

You can convert individual responses too if needed:

Example

    var transformer = require('postman-collection-transformer'),

        objectToConvert = { /* A v1 Response or a v2 Response */ },

        options = {
            inputVersion: '1.0.0',
            outputVersion: '2.0.0',
            retainIds: true  // the transformer strips request-ids etc by default.
        };

    transformer.convertResponse(objectToConvert, options, function (err, converted) {
        console.log(converted);
    });

Normalizing v1 collections

The transformer also provides a Command line API to normalize collections for full forward compatibility.

Example:

$ postman-collection-transformer normalize \
    --input ./v1-collection.json \
    --normalize-version 1.0.0 \
    --output ./v1-norm-collection.json \
    --pretty \
    --overwrite

All options:

$ postman-collection-transformer normalize -h

  Usage: normalize [options]

  Normalizes a postman collection according to the provided version


  Options:

    -i, --input <path>                 Path to the collection JSON file to be normalized
    -n, --normalize-version <version>  The version to normalizers the provided collection on
    -o, --output <path>                Path to the target file, where the normalized collection will be written
    -P, --pretty                       Pretty print the output
    --retain-ids                       Retain the request and folder IDs during conversion (collection ID is always retained)
    -w, --overwrite                    Overwrite the output file if it exists
    -h, --help                         Output usage information

If you'd rather use the transformer as a library:

    var transformer = require('postman-collection-transformer'),
        collection = require('./path/to/collection.json'),
        inspect = require('util').inspect,

        options = {
            normalizeVersion: '1.0.0',
            mutate: false, // performs in-place normalization, false by default.
            noDefaults: false, // when set to true, sensible defaults for missing properties are skipped. Default: false
            prioritizeV2: false, // when set to true, v2 attributes are used as the source of truth for normalization.
            retainEmptyValues: false, // when set to true, empty values are set to '', not removed. False by default.
            retainIds: true  // the transformer strips request-ids etc by default.
        };

    transformer.normalize(collection, options, function (error, result) {
        if (error) {
            return console.error(error);
        }

        // result <== the converted collection as a raw Javascript object
        console.log(inspect(result, {colors: true, depth: 10000}));
    });