postman

Documentation

Overview

Package postman provides an adapter for converting Postman Collection v2.1 to IR format.

This converter provides lossless conversion, preserving:

• Request/response details (method, URL, headers, body)
• Folder structure as tags
• Collection metadata (name, description, version)
• Saved example responses
• Request descriptions
• Variable resolution
• Authentication configuration

Index

• func ConvertFileToBatch(path string, opts ...ConverterOption) (*ir.Batch, error)
• func ConvertFileToRecords(path string, opts ...ConverterOption) ([]ir.IRRecord, error)
• func GenerateUUID() string
• func Read(r io.Reader) (*postman.Collection, error)
• func ReadFile(path string) (*postman.Collection, error)
• type ConvertResult
  • func ConvertFile(path string, opts ...ConverterOption) (*ConvertResult, error)
• type Converter
  • func NewConverter() *Converter
  • func (c *Converter) Convert(collection *postman.Collection) (*ConvertResult, error)
  • func (c *Converter) ConvertToBatch(collection *postman.Collection) (*ir.Batch, error)
  • func (c *Converter) ConvertToRecords(collection *postman.Collection) ([]ir.IRRecord, error)
• type ConverterOption
  • func WithBaseURL(url string) ConverterOption
  • func WithDisabledItems() ConverterOption
  • func WithHeaderFilter(headers ...string) ConverterOption
  • func WithVariable(key, value string) ConverterOption
  • func WithVariables(vars map[string]string) ConverterOption
  • func WithoutAuth() ConverterOption
  • func WithoutHeaders() ConverterOption
  • func WithoutIDs() ConverterOption

Functions

func ConvertFileToBatch

func ConvertFileToBatch(path string, opts ...ConverterOption) (*ir.Batch, error)

ConvertFileToBatch is a convenience function that reads and converts to an IR batch.

func ConvertFileToRecords

func ConvertFileToRecords(path string, opts ...ConverterOption) ([]ir.IRRecord, error)

ConvertFileToRecords is a convenience function that reads and converts to IR records.

func GenerateUUID

func GenerateUUID() string

GenerateUUID generates a new UUID string.

func Read

func Read(r io.Reader) (*postman.Collection, error)

Read reads a Postman collection from an io.Reader.

func ReadFile

func ReadFile(path string) (*postman.Collection, error)

ReadFile reads a Postman collection from a file path.

Types

type ConvertResult

type ConvertResult struct {
	// Records is the list of converted IR records.
	Records []ir.IRRecord

	// Metadata contains API-level metadata from the collection.
	Metadata *ir.APIMetadata

	// TagDefinitions contains tag definitions from folder structure.
	TagDefinitions []ir.TagDefinition

	// Warnings contains non-fatal issues encountered during conversion.
	Warnings []string
}

ConvertResult contains the conversion output.

func ConvertFile

func ConvertFile(path string, opts ...ConverterOption) (*ConvertResult, error)

ConvertFile is a convenience function that reads and converts a Postman collection file.

type Converter

type Converter struct {
	// Variables is a map of variable names to values for resolution.
	// Collection-level variables are added automatically.
	Variables map[string]string

	// BaseURL is the value to use for {{url}} or {{baseUrl}} variables.
	BaseURL string

	// IncludeHeaders controls whether to include HTTP headers in output.
	IncludeHeaders bool

	// IncludeDisabled includes disabled headers and query params.
	IncludeDisabled bool

	// FilterHeaders is a list of header names to exclude (case-insensitive).
	// By default, sensitive auth headers are not filtered since Postman collections
	// typically contain example/placeholder values.
	FilterHeaders []string

	// GenerateIDs controls whether to generate UUIDs for records without IDs.
	GenerateIDs bool

	// PreserveAuth converts Postman auth configurations to request headers.
	PreserveAuth bool
}

Converter converts Postman collections to IR records.

func NewConverter

func NewConverter() *Converter

NewConverter creates a new Postman to IR converter with default settings.

func (*Converter) Convert

func (c *Converter) Convert(collection *postman.Collection) (*ConvertResult, error)

Convert converts a Postman collection to IR records with full metadata.

func (*Converter) ConvertToBatch

func (c *Converter) ConvertToBatch(collection *postman.Collection) (*ir.Batch, error)

ConvertToBatch converts a collection to a complete IR batch.

func (*Converter) ConvertToRecords

func (c *Converter) ConvertToRecords(collection *postman.Collection) ([]ir.IRRecord, error)

ConvertToRecords is a convenience method that returns only the IR records.

type ConverterOption

type ConverterOption func(*Converter)

ConverterOption is a functional option for configuring the converter.

func WithBaseURL

func WithBaseURL(url string) ConverterOption

WithBaseURL sets the base URL for variable resolution.

func WithDisabledItems

func WithDisabledItems() ConverterOption

WithDisabledItems includes disabled headers and query params.

func WithHeaderFilter

func WithHeaderFilter(headers ...string) ConverterOption

WithHeaderFilter adds headers to filter out.

func WithVariable

func WithVariable(key, value string) ConverterOption

WithVariable sets a single variable for resolution.

func WithVariables

func WithVariables(vars map[string]string) ConverterOption

WithVariables sets additional variables for resolution.

func WithoutAuth

func WithoutAuth() ConverterOption

WithoutAuth disables auth-to-header conversion.

func WithoutHeaders

func WithoutHeaders() ConverterOption

WithoutHeaders disables header inclusion.

func WithoutIDs

func WithoutIDs() ConverterOption

WithoutIDs disables automatic ID generation.