postman

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: GPL-3.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions 

func AddDocLinks(items []CollectionItem, baseDocURL string)

AddDocLinks appends a Markdown doc link to each leaf request's description.

func ApplyAuth 

func ApplyAuth(col *Collection, authCfg *config.Auth) error

ApplyAuth sets the collection-level auth from config.

func ApplyCommonHeaders 

func ApplyCommonHeaders(items []CollectionItem, headers []config.Header)

ApplyCommonHeaders injects the configured headers into every leaf request. If a header with the same key already exists, its value and disabled flag are updated. Otherwise the header is appended.

func ApplyCommonQueryParams added in v0.2.0 

func ApplyCommonQueryParams(items []CollectionItem, params []config.QueryParam)

ApplyCommonQueryParams injects the configured query parameters into every leaf request. If a parameter with the same key already exists, its value and disabled flag are updated. Otherwise the parameter is appended.

func ApplyFolderOverrides 

func ApplyFolderOverrides(items []CollectionItem, overrides map[string]config.FolderOverride) error

ApplyFolderOverrides applies per-folder auth/script overrides. Matching is case-sensitive on the folder name.

func ApplyScripts 

func ApplyScripts(col *Collection, scriptsCfg *config.Scripts)

ApplyScripts sets collection-level pre-request and test events from config.

func CountRequests added in v0.2.0 

func CountRequests(items []CollectionItem) int

CountRequests returns the number of leaf requests in an item tree.

func PropagateAuthInherit 

func PropagateAuthInherit(items []CollectionItem, overrides map[string]config.FolderOverride)

PropagateAuthInherit clears the auth on every folder and leaf request so that they inherit authentication from their parent (collection or enclosing folder).

Rules:

  • Items whose auth type is "noauth" are left untouched – they explicitly opt out of authentication and should not be changed.
  • Items with nil auth are already inheriting; they are skipped.
  • Folders whose name appears as a key in overrides are skipped (only the folder itself; its children are still processed so they can inherit from the overridden folder).
  • For leaf requests, both CollectionItem.Auth and Request.Auth are cleared.

func SetBaseURL 

func SetBaseURL(items []CollectionItem, baseURL string)

SetBaseURL replaces the host (and protocol/port) of every request URL with baseURL. If baseURL starts with "{{" it is treated as a Postman variable.

func SyncRawQuery added in v0.2.0 

func SyncRawQuery(items []CollectionItem)

SyncRawQuery rewrites the query string of every request's raw URL from its enabled query params, the way Postman builds it. Run it after anything that changes query params or their enabled state, so raw does not go stale.

Types

type Auth 

type Auth struct {
	Type     string          `json:"type"`
	APIKey   []AuthAttribute `json:"apikey,omitempty"`
	Basic    []AuthAttribute `json:"basic,omitempty"`
	Bearer   []AuthAttribute `json:"bearer,omitempty"`
	OAuth1   []AuthAttribute `json:"oauth1,omitempty"`
	OAuth2   []AuthAttribute `json:"oauth2,omitempty"`
	Digest   []AuthAttribute `json:"digest,omitempty"`
	NTLM     []AuthAttribute `json:"ntlm,omitempty"`
	Hawk     []AuthAttribute `json:"hawk,omitempty"`
	AWSv4    []AuthAttribute `json:"awsv4,omitempty"`
	EdgeGrid []AuthAttribute `json:"edgegrid,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Auth holds Postman authentication configuration.

func BuildAuth 

func BuildAuth(authType string, attrs []AuthAttribute) (*Auth, error)

BuildAuth constructs a postman.Auth from the given type and attributes. Attributes are placed under the matching type key.

func (Auth) MarshalJSON added in v0.2.0 

func (v Auth) MarshalJSON() ([]byte, error)

func (*Auth) UnmarshalJSON added in v0.2.0 

func (v *Auth) UnmarshalJSON(b []byte) error

type AuthAttribute 

type AuthAttribute struct {
	Key   string `json:"key"`
	Value any    `json:"value,omitempty"`
	Type  string `json:"type,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

AuthAttribute is a key/value attribute for an auth method.

func (AuthAttribute) MarshalJSON added in v0.2.0 

func (v AuthAttribute) MarshalJSON() ([]byte, error)

func (*AuthAttribute) UnmarshalJSON added in v0.2.0 

func (v *AuthAttribute) UnmarshalJSON(b []byte) error

type Body 

type Body struct {
	Mode       string      `json:"mode,omitempty"`
	Raw        string      `json:"raw,omitempty"`
	FormData   []FormParam `json:"formdata,omitempty"`
	URLEncoded []FormParam `json:"urlencoded,omitempty"`
	Disabled   bool        `json:"disabled,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Body holds request body data.

func (Body) MarshalJSON added in v0.2.0 

func (v Body) MarshalJSON() ([]byte, error)

func (*Body) UnmarshalJSON added in v0.2.0 

func (v *Body) UnmarshalJSON(b []byte) error

type ChangeKind added in v0.2.0 

type ChangeKind string

ChangeKind classifies an ItemChange. 

const (
	ChangeAdded    ChangeKind = "added"
	ChangeRemoved  ChangeKind = "removed"
	ChangeModified ChangeKind = "modified"
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a minimal Postman API client.

func NewClient 

func NewClient(apiKey, workspaceID string) *Client

NewClient creates a new Postman API client.

func (*Client) CreateCollection 

func (c *Client) CreateCollection(data *CollectionWrapper) error

CreateCollection creates a new collection in the workspace.

func (*Client) CreateEnvironment added in v0.1.0 

func (c *Client) CreateEnvironment(env *EnvironmentWrapper) error

CreateEnvironment creates a new environment in the workspace.

func (*Client) DeleteCollection 

func (c *Client) DeleteCollection(id string) error

DeleteCollection deletes a collection by ID/UID. Errors are logged but not fatal.

func (*Client) DeleteEnvironment added in v0.1.0 

func (c *Client) DeleteEnvironment(id string) error

DeleteEnvironment deletes an environment by ID/UID.

func (*Client) GetCollection 

func (c *Client) GetCollection(id string) (*CollectionWrapper, error)

GetCollection fetches a full collection by its ID or UID.

func (*Client) GetEnvironment added in v0.1.0 

func (c *Client) GetEnvironment(id string) (*EnvironmentWrapper, error)

GetEnvironment fetches a full environment by its ID or UID.

func (*Client) GetWorkspaceCollections 

func (c *Client) GetWorkspaceCollections() (map[string]string, error)

GetWorkspaceCollections returns a map of collection name → collection ID for all collections in the configured workspace.

func (*Client) GetWorkspaceEnvironments added in v0.1.0 

func (c *Client) GetWorkspaceEnvironments() (map[string]string, error)

GetWorkspaceEnvironments returns a map of environment name → environment UID for all environments in the configured workspace.

func (*Client) ImportOpenAPI 

func (c *Client) ImportOpenAPI(spec map[string]any, options map[string]any) (string, error)

ImportOpenAPI uploads an OpenAPI spec to Postman and returns the UID of the temporary collection that Postman generates. options are forwarded to Postman's OpenAPI importer (e.g. enableOptionalParameters); nil sends none.

func (*Client) UpdateCollection 

func (c *Client) UpdateCollection(id string, data *CollectionWrapper) error

UpdateCollection replaces an existing collection with new data.

func (*Client) UpdateEnvironment added in v0.1.0 

func (c *Client) UpdateEnvironment(id string, env *EnvironmentWrapper) error

UpdateEnvironment replaces an existing environment with new data.

type Collection 

type Collection struct {
	Info      Info             `json:"info"`
	Items     []CollectionItem `json:"item"`
	Auth      *Auth            `json:"auth,omitempty"`
	Events    []Event          `json:"event,omitempty"`
	Variables []Variable       `json:"variable,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Collection is a Postman Collection v2.1.

func (Collection) MarshalJSON added in v0.2.0 

func (v Collection) MarshalJSON() ([]byte, error)

func (*Collection) UnmarshalJSON added in v0.2.0 

func (v *Collection) UnmarshalJSON(b []byte) error

type CollectionItem 

type CollectionItem struct {
	// Leaf request fields
	ID          string     `json:"id,omitempty"`
	Name        string     `json:"name,omitempty"`
	Description string     `json:"description,omitempty"`
	Request     *Request   `json:"request,omitempty"`
	Responses   []any      `json:"response,omitempty"`
	Events      []Event    `json:"event,omitempty"`
	Auth        *Auth      `json:"auth,omitempty"`
	Variables   []Variable `json:"variable,omitempty"`

	// Folder-only field: if non-nil, this item is a folder.
	Items *[]CollectionItem `json:"item,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

CollectionItem is a union of Item (request leaf) and ItemGroup (folder). We distinguish them by the presence of the "item" key (folder) vs "request" key (leaf).

func FlattenSingleFolders 

func FlattenSingleFolders(items []CollectionItem) []CollectionItem

FlattenSingleFolders unwraps any folder that contains exactly one request whose name matches the folder name, replacing the folder with the request.

func MergeItems 

func MergeItems(old, new []CollectionItem) []CollectionItem

MergeItems merges a newly-generated collection's items into the existing collection's items, preserving manual customisations.

Rules:

  • Items matched by name: update request fields (url, method, body, headers, description) from new; keep auth and events (scripts) from old.
  • Items only in new: added as-is (new endpoints).
  • Items only in old: removed (spec is source of truth).
  • Folders are recursed into.

Request data (headers, params, body) always comes from new; use MergeItemsWith to preserve the user's edits.

func MergeItemsWith added in v0.2.0 

func MergeItemsWith(old, new []CollectionItem, opts MergeOptions) []CollectionItem

MergeItemsWith is MergeItems with configurable request merging.

func SortItemsAlpha 

func SortItemsAlpha(items []CollectionItem) []CollectionItem

SortItemsAlpha sorts items alphabetically by name at every level.

func (*CollectionItem) IsFolder 

func (ci *CollectionItem) IsFolder() bool

IsFolder reports whether this CollectionItem is a folder (item-group).

func (CollectionItem) MarshalJSON added in v0.2.0 

func (v CollectionItem) MarshalJSON() ([]byte, error)

func (*CollectionItem) UnmarshalJSON added in v0.2.0 

func (v *CollectionItem) UnmarshalJSON(b []byte) error

type CollectionWrapper 

type CollectionWrapper struct {
	Collection Collection `json:"collection"`
}

CollectionWrapper is the root envelope returned by the Postman API.

type Environment added in v0.1.0 

type Environment struct {
	ID     string             `json:"id,omitempty"`
	Name   string             `json:"name"`
	Values []EnvironmentValue `json:"values"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Environment is a Postman environment with a list of variables.

func (Environment) MarshalJSON added in v0.2.0 

func (v Environment) MarshalJSON() ([]byte, error)

func (*Environment) UnmarshalJSON added in v0.2.0 

func (v *Environment) UnmarshalJSON(b []byte) error

type EnvironmentValue added in v0.1.0 

type EnvironmentValue struct {
	Key     string `json:"key"`
	Value   string `json:"value"`
	Type    string `json:"type,omitempty"`
	Enabled bool   `json:"enabled"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

EnvironmentValue is a single variable in a Postman environment.

func (EnvironmentValue) MarshalJSON added in v0.2.0 

func (v EnvironmentValue) MarshalJSON() ([]byte, error)

func (*EnvironmentValue) UnmarshalJSON added in v0.2.0 

func (v *EnvironmentValue) UnmarshalJSON(b []byte) error

type EnvironmentWrapper added in v0.1.0 

type EnvironmentWrapper struct {
	Environment Environment `json:"environment"`
}

EnvironmentWrapper is the root envelope for Postman environment API responses.

type Event 

type Event struct {
	Listen   string `json:"listen"`
	Script   Script `json:"script"`
	Disabled bool   `json:"disabled,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Event is a Postman script event (prerequest or test).

func (Event) MarshalJSON added in v0.2.0 

func (v Event) MarshalJSON() ([]byte, error)

func (*Event) UnmarshalJSON added in v0.2.0 

func (v *Event) UnmarshalJSON(b []byte) error

type Extra added in v0.2.0 

type Extra map[string]json.RawMessage

Extra holds JSON fields that are not explicitly modelled by a struct.

Postman's collection format is much richer than what this tool needs to manipulate (descriptions, body options, form data, protocol profile behaviour, ...). Types embedding an Extra field keep those unknown fields on decode and write them back on encode, so a fetch → transform → update cycle never silently drops data.

type FormParam added in v0.2.0 

type FormParam struct {
	Key      string `json:"key"`
	Type     string `json:"type,omitempty"`
	Disabled bool   `json:"disabled,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

FormParam is a single form-data or urlencoded body field. Its value (which Postman may send as null) and file src are kept in Extra.

func (FormParam) MarshalJSON added in v0.2.0 

func (v FormParam) MarshalJSON() ([]byte, error)

func (*FormParam) UnmarshalJSON added in v0.2.0 

func (v *FormParam) UnmarshalJSON(b []byte) error
type Header struct {
	Key      string `json:"key"`
	Value    string `json:"value"`
	Disabled bool   `json:"disabled,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Header is a single HTTP header.

func (Header) MarshalJSON added in v0.2.0 

func (v Header) MarshalJSON() ([]byte, error)

func (*Header) UnmarshalJSON added in v0.2.0 

func (v *Header) UnmarshalJSON(b []byte) error

type Info 

type Info struct {
	PostmanID string `json:"_postman_id,omitempty"`
	Name      string `json:"name"`
	Schema    string `json:"schema"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Info holds metadata about the collection.

func (Info) MarshalJSON added in v0.2.0 

func (v Info) MarshalJSON() ([]byte, error)

func (*Info) UnmarshalJSON added in v0.2.0 

func (v *Info) UnmarshalJSON(b []byte) error

type ItemChange added in v0.2.0 

type ItemChange struct {
	Path    string
	Kind    ChangeKind
	Details []string
}

ItemChange describes how one folder or request differs between two collections. Path joins folder and item names with "/".

func DiffCollections added in v0.2.0 

func DiffCollections(old, new *Collection) []ItemChange

DiffCollections is DiffItems plus collection-level auth and scripts.

func DiffItems added in v0.2.0 

func DiffItems(old, new []CollectionItem) []ItemChange

DiffItems compares two item trees matched by name, like MergeItems, and returns the changes needed to turn old into new: changes in new's order, followed by removals in old's order. Added or removed folders are reported as a whole rather than request by request.

type MergeOptions added in v0.2.0 

type MergeOptions struct {
	// PreserveRequestData keeps header/param values, enabled state and body
	// edits from old, see mergeRequest.
	PreserveRequestData bool

	// Baseline is the collection generated by the previous sync. When a
	// request is found in it, the merge is three-way: data the user has not
	// changed since the baseline follows the spec, edited data is kept, and
	// hand-added/deleted entries are detected exactly. Requests missing from
	// the baseline (or a nil Baseline) use the two-way rules.
	Baseline []CollectionItem
}

MergeOptions tunes how MergeItemsWith reconciles matched leaf requests.

type Request 

type Request struct {
	Method      string   `json:"method,omitempty"`
	URL         *URL     `json:"url,omitempty"`
	Header      []Header `json:"header,omitempty"`
	Body        *Body    `json:"body,omitempty"`
	Auth        *Auth    `json:"auth,omitempty"`
	Description string   `json:"description,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Request represents an HTTP request.

func (Request) MarshalJSON added in v0.2.0 

func (v Request) MarshalJSON() ([]byte, error)

func (*Request) UnmarshalJSON added in v0.2.0 

func (v *Request) UnmarshalJSON(b []byte) error

type Script 

type Script struct {
	Type string   `json:"type,omitempty"`
	Exec []string `json:"exec"`
	Name string   `json:"name,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Script holds a JavaScript snippet.

func (Script) MarshalJSON added in v0.2.0 

func (v Script) MarshalJSON() ([]byte, error)

func (*Script) UnmarshalJSON added in v0.2.0 

func (v *Script) UnmarshalJSON(b []byte) error

type URL 

type URL struct {
	Raw      string     `json:"raw,omitempty"`
	Protocol string     `json:"protocol,omitempty"`
	Host     []string   `json:"host,omitempty"`
	Path     []string   `json:"path,omitempty"`
	Port     string     `json:"port,omitempty"`
	Query    []URLParam `json:"query,omitempty"`
	Variable []Variable `json:"variable,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

URL holds the broken-down URL of a request.

func (URL) MarshalJSON added in v0.2.0 

func (v URL) MarshalJSON() ([]byte, error)

func (*URL) UnmarshalJSON added in v0.2.0 

func (v *URL) UnmarshalJSON(b []byte) error

type URLParam 

type URLParam struct {
	Key      *string `json:"key"`
	Value    *string `json:"value"`
	Disabled bool    `json:"disabled,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

URLParam is a query parameter.

func (URLParam) MarshalJSON added in v0.2.0 

func (v URLParam) MarshalJSON() ([]byte, error)

func (*URLParam) UnmarshalJSON added in v0.2.0 

func (v *URLParam) UnmarshalJSON(b []byte) error

type Variable 

type Variable struct {
	Key   string `json:"key,omitempty"`
	Value string `json:"value,omitempty"`
	Type  string `json:"type,omitempty"`
	Name  string `json:"name,omitempty"`

	// Extra preserves fields not modelled above.
	Extra Extra `json:"-"`
}

Variable is a Postman variable.

func (Variable) MarshalJSON added in v0.2.0 

func (v Variable) MarshalJSON() ([]byte, error)

func (*Variable) UnmarshalJSON added in v0.2.0 

func (v *Variable) UnmarshalJSON(b []byte) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.