API REST

Collection ⇐ ItemGroup

Kind: global class
Extends: ItemGroup

• Collection ⇐ ItemGroup
  • new Collection([definition], [environments])
  • instance
    • .variables : VariableList
    • .version : Version
    • .events : EventList
    • .items : PropertyList.<(Item|ItemGroup)>
    • .auth : RequestAuth
    • .id : String
    • .name : String
    • .disabled : Boolean
    • .description : Description
    • .syncVariablesFrom(obj, [track]) ⇒ Object
    • .syncVariablesTo([obj]) ⇒ Object
    • .toJSON() ⇒ Object
    • .describe(content, [type])
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • static
    • .isCollection(obj) ⇒ Boolean
  • inner
    • ~definition

new Collection([definition], [environments])

Create or load an instance of Postman Collection as a JavaScript object that can be manipulated easily.

A collection lets you group individual requests together. These requests can be further organized into folders to accurately mirror your API. Requests can also store sample responses when saved in a collection. You can add metadata like name and description too so that all the information that a developer needs to use your API is available easily.

Param	Type	Description
[definition]	definition	Pass the initial definition of the collection (name, id, etc) as the definition parameter. The definition object is structured exactly as the collection format as defined in https://www.schema.getpostman.com/. This parameter is optional. That implies that you can create an empty instance of collection and add requests and other properties in order to build a new collection.
[environments]	Array.<Object>	The collection instance constructor accepts the second parameter as an array of environment objects. Environments objects store variable definitions that are inherited by variables. These environment variables are usually the ones that are exported from the Postman App to use them with different collections. Refer to Postman documentation on environment variables.

Example (Load a Collection JSON file from disk)

var fs = require('fs'), // needed to read JSON file from disk
    pretty = function (obj) { // function to neatly log the collection object to console
        return require('util').inspect(obj, {colors: true});
    },
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// log items at root level of the collection
console.log(inspect(myCollection));

Example (Create a blank collection and write to file)

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    mycollection;

myCollection = new Collection({
    info: {
        name: "my Collection"
    }
});

// log the collection to console to see its contents
fs.writeFileSync('myCollection.postman_collection', myCollection.toString());

collection.variables : VariableList

The variables property holds a list of variables that are associated with a Collection. These variables are stored within a collection so that they can be re-used and replaced in rest of the collection. For example, if one has a variable named port with value 8080, then one can write a request Url as http://localhost:{{port}}/my/endpoint and that will be replaced to form http://localhost:8080/my/endpoint. Collection Variables are like environment variables, but stored locally within a collection.

Kind: instance property of Collection
Example (Creating a collection with variables)

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    mycollection;

// Create a new empty collection.
myCollection = new Collection();

// Add a variable to the collection
myCollection.variables.add({
    id: 'apiBaseUrl',
    value: 'http://timeapi.org',
    type: 'string'
});

//Add a request that uses the variable that we just added.
myCollection.items.add({
    id: 'utc-time-now',
    name: 'Get the current time in UTC',
    request: '{{apiBaseUrl}}/utc/now'
});

collection.version : Version

The version key in collection is used to express the version of the collection. It is useful in either tracking development iteration of an API server or the version of an API itself. It can also be used to represent the number of iterations of the collection as it is updated through its lifetime.

Version is expressed in semver format.

Kind: instance property of Collection
Optional:
See: http://semver.org/

collection.events : EventList

In this list, one can define the Scripts to be executed when an event is triggered. Events are triggered before certain actions are taken on a Collection, Request, etc. For example, executing a request causes the prerequest and the test events to be triggered.

Kind: instance property of Collection
Example (Executing a common test script for all requests in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Add an event listener to the collection that listens to the `test` event.
myCollection.events.add({
    listen: 'test',
    script: {
        exec: 'tests["Status code is 200"] = (responseCode.code === 200)'
    }
});

collection.items : PropertyList.<(Item|ItemGroup)>

This is a PropertyList that holds the list of Items or ItemGroups belonging to a Collection or to an ItemGroup. Operation on an individual item in this list can be performed using various functions available to a PropertyList.

Kind: instance property of Collection
Example (Fetch empty ItemGroups in a list loaded from a file)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection,
    emptyGroups;
// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Filter items in Collection root that is an empty ItemGroup
emptyGroups = myCollection.items.filter(function (item) {
    return item && item.items && (item.items.count() === 0);
});

// Log the emptyGroups array to check it's contents
console.log(emptyGroups);

collection.auth : RequestAuth

One can define the default authentication method required for every item that belongs to this list. Individual Requests can override this in their own definitions. More on how to define an authentication method is outlined in the RequestAuth property.

Kind: instance property of Collection
Example (Define an entire ItemGroup (folder) or Collection to follow Basic Auth)

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    RequestAuth = require('postman-collection').RequestAuth,
    mycollection;

// Create a collection having two requests
myCollection = new Collection();
myCollection.items.add([
    { name: 'GET Request', request: 'https://postman-echo.com/get?auth=basic' },
    { name: 'PUT Request', request: 'https://postman-echo.com/put?auth=basic' }
]);

// Add basic auth to the Collection, to be applied on all requests.
myCollection.auth = new RequestAuth({
    type: 'basic',
    username: 'postman',
    password: 'password'
});

collection.id : String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Kind: instance property of Collection
Note: The property can also be present in the postman_id meta in case it is not specified in the object. An auto-generated property is used wherever one is not specified

collection.name : String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Kind: instance property of Collection

collection.disabled : Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Kind: instance property of Collection
Optional:

collection.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of Collection
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

collection.syncVariablesFrom(obj, [track]) ⇒ Object

Using this function, one can sync the values of collection variables from a reference object.

Kind: instance method of Collection

Param	Type
obj	Object
[track]	Boolean

collection.syncVariablesTo([obj]) ⇒ Object

Transfer the variables in this scope to an object

Kind: instance method of Collection

Param	Type
[obj]	Object

collection.toJSON() ⇒ Object

Convert the collection to JSON compatible plain object

Kind: instance method of Collection
Overrides: toJSON

collection.describe(content, [type])

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Kind: instance method of Collection

Param	Type	Default	Description
content	String		The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
[type]	String	"text/plain"	The type of the content can be one of the values mentioned in format enumeration - namely text/plain, text/markdown or text/html.

Example (Add a description to an instance of Collection)

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

collection.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of Collection
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

collection.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of Collection

Param	Type
property	String

collection.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of Collection

collection.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of Collection

Collection.isCollection(obj) ⇒ Boolean

Check whether an object is an instance of ItemGroup.

Kind: static method of Collection

Param	Type
obj	*

Collection~definition

The following is the object structure accepted as constructor parameter while calling new Collection(...). It is also the structure exported when toJSON or Property#toObjectResolved is called on a collection instance.

Kind: inner typedef of Collection
See: {ItemGroup~definition} - Since Collection inherits ItemGroup, the properties supported by ItemGroup are applicable as well.
Properties

Name	Type	Description
info	Object	The meta information regarding the collection is provided as the info object.
info.id	String	Every collection is identified by the unique value of this property. It is recommended that you maintain the same id since changing the id usually implies that is a different collection than it was originally.
info.name	String	A collection's friendly name is defined by this property. You would want to set this field to a value that would allow you to easily identify this collection among a bunch of other collections.
info.version	String	Postman allows you to version your collections as they grow, and this field holds the version number. While optional, it is recommended that you use this field to its fullest extent.
item	Array.<(Itemdefinition|ItemGroupdefinition)>	Items are the basic unit for a Postman collection. You can think of them as corresponding to a single API endpoint. Each Item has one request and may have multiple API responses associated with it.
variable	Object.<definition>	Collection variables allow you to define a set of variables, that are a part of the collection, as opposed to environments, which are separate entities.
version	String | Version~definition	Version of the collection expressed in semver format.

Example (JSON definition of an example collection)

{
    "info": {
        "name": "My Postman Collection",
        "version": "1.0.0"
    }
    "item": [{
        "request": "{{base-url}}/get"
    }],
    "variables": [{
        "id": "base-url",
        "value": "https://postman-echo.com"
    }]
}

Cookie ⇐ PropertyBase

Kind: global class
Extends: PropertyBase

• Cookie ⇐ PropertyBase
  • new Cookie([options])
  • instance
    • .name : String
    • .expires : Date | String
    • .maxAge : Number
    • .domain : String
    • .path : String
    • .secure
    • .httpOnly
    • .hostOnly
    • .session
    • .value : String
    • .extensions : Array
    • .description : Description
    • .valueOf() ⇒ String
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .toJSON()
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • static
    • .isCookie(obj) ⇒ Boolean
    • .parse(str) ⇒ *
  • inner
    • ~definition

new Cookie([options])

A Postman Cookie definition that comprehensively represents an HTTP Cookie.

Param	Type	Description
[options]	definition	Pass the initial definition of the Cookie.

Example (Create a new Cookie)

var Cookie = require('postman-collection').Cookie,
    myCookie = new Cookie({
         name: 'my-cookie-name',
         expires: '1464769543832', // UNIX timestamp, in *milliseconds*
         maxAge: '300'  // In seconds. In this case, the Cookie is valid for 5 minutes
         domain: 'something.example.com',
         path: '/',
         secure: false,
         httpOnly: true,
         session: false,
         value: 'my-cookie-value',
         extensions: [{
             key: 'Priority',
             value: 'HIGH'
         }]
    });

Example (Parse a Cookie Header)

var Cookie = require('postman-collection').Cookie,
    rawHeader = 'myCookie=myValue;Path=/;Expires=Sun, 04-Feb-2018 14:18:27 GMT;Secure;HttpOnly;Priority=HIGH'
    myCookie = new Cookie(rawHeader);

console.log(myCookie.toJSON());

cookie.name : String

The name of the cookie.

Kind: instance property of Cookie

cookie.expires : Date | String

Expires sets an expiry date for when a cookie gets deleted. It should either be a date object or timestamp string of date.

Kind: instance property of Cookie
Note: The value for this option is a date in the format Wdy, DD-Mon-YYYY HH:MM:SS GMT such as "Sat, 02 May 2009 23:38:25 GMT". Without the expires option, a cookie has a lifespan of a single session. A session is defined as finished when the browser is shut down, so session cookies exist only while the browser remains open. If the expires option is set to a date that appears in the past, then the cookie is immediately deleted in browser.
Todo

• Accept date object and convert stringified date (timestamp only) to date object

cookie.maxAge : Number

Max-age sets the time in seconds for when a cookie will be deleted.

Kind: instance property of Cookie

cookie.domain : String

Indicates the domain(s) for which the cookie should be sent.

Kind: instance property of Cookie
Note: By default, domain is set to the host name of the page setting the cookie, so the cookie value is sent whenever a request is made to the same host name. The value set for the domain option must be part of the host name that is sending the Set-Cookie header. The SDK does not perform this check, but the underlying client that actually sends the request could do it automatically.

cookie.path : String

Kind: instance property of Cookie
Note: On server, the default value for the path option is the path of the URL that sent the Set-Cookie header.

cookie.secure

A secure cookie will only be sent to the server when a request is made using SSL and the HTTPS protocol. The idea that the contents of the cookie are of high value and could be potentially damaging to transmit as clear text.

Kind: instance property of Cookie
Type:: Boolean

cookie.httpOnly

The idea behind HTTP-only cookies is to instruct a browser that a cookie should never be accessible via JavaScript through the document.cookie property. This feature was designed as a security measure to help prevent cross-site scripting (XSS) attacks perpetrated by stealing cookies via JavaScript.

Kind: instance property of Cookie
Type:: Boolean

cookie.hostOnly

Kind: instance property of Cookie
Type:: Boolean

cookie.session

Indicates whether this is a Session Cookie.

Kind: instance property of Cookie
Type:: Boolean

cookie.value : String

Kind: instance property of Cookie
Note: The commonly held belief is that cookie values must be URL-encoded, but this is a fallacy even though it is the de facto implementation. The original specification indicates that only three types of characters must be encoded: semicolon, comma, and white space. The specification indicates that URL encoding may be used but stops short of requiring it. The RFC makes no mention of encoding whatsoever. Still, almost all implementations perform some sort of URL encoding on cookie values.

cookie.extensions : Array

Any extra parameters that are not strictly a part of the Cookie spec go here.

Kind: instance property of Cookie

cookie.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of Cookie
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

cookie.valueOf() ⇒ String

Get the value of this cookie

Kind: instance method of Cookie

cookie.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of Cookie
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

cookie.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of Cookie

Param	Type
property	String

cookie.toJSON()

Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.

Kind: instance method of Cookie

cookie.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of Cookie

cookie.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of Cookie

Cookie.isCookie(obj) ⇒ Boolean

Check whether an object is an instance of PostmanCookie.

Kind: static method of Cookie

Param	Type
obj	*

Cookie.parse(str) ⇒ *

Cookie header parser

Kind: static method of Cookie
Returns: * - A plain cookie options object, use it to create a new Cookie

Param
str

Cookie~definition

The following is the object structure accepted as constructor parameter while calling new Cookie(...). It is also the structure exported when toJSON or Property#toObjectResolved is called on a Cookie instance.

Kind: inner typedef of Cookie
Properties

Name	Type	Description
key	String	The name of the cookie. Some call it the "name".
value	String	The value stored in the Cookie
expires	String	Expires sets an expiry date for when a coo0kie gets deleted. It should either be a date object or timestamp string of date.
maxAge	Number	Max-age sets the time in seconds for when a cookie will be deleted.
domain	String	Indicates the domain(s) for which the cookie should be sent.
path	String	Limits the scope of the cookie to a specified path, e.g: "/accounts"
secure	Boolean	A secure cookie will only be sent to the server when a request is made using SSL and the HTTPS protocol. The idea that the contents of the cookie are of high value and could be potentially damaging to transmit as clear text.
httpOnly	Boolean	The idea behind HTTP-only cookies is to instruct a browser that a cookie should never be accessible via JavaScript through the document.cookie property. This feature was designed as a security measure to help prevent cross-site scripting (XSS) attacks perpetrated by stealing cookies via JavaScript.
hostOnly	Boolean	Indicates that this cookie is only valid for the given domain (and not its parent or child domains.)
session	Boolean	Indicates whether this is a Session Cookie. (A transient cookie, which is deleted at the end of an HTTP session.)
extensions	Array	Any extra attributes that are extensions to the original Cookie specification can be specified here.
extensions[].key	String	Name of the extension.
extensions[].value	String	Value of the extension

Example (JSON definition of an example collection)

{
    key: 'my-cookie-name',
    expires: '1464769543832', // UNIX timestamp, in *milliseconds*
    maxAge: '300'  // In seconds. In this case, the Cookie is valid for 5 minutes
    domain: 'something.example.com',
    path: '/',
    secure: false,
    httpOnly: true,
    session: false,
    value: 'my-cookie-value',
    extensions: [{
        key: 'Priority',
        value: 'HIGH'
    }]
}

Description

Kind: global class

• Description
  • new Description([definition])
  • instance
    • .content : String
    • .type : String
    • .update(content, [type])
    • .toString() ⇒ String
    • .toJSON() ⇒ Object
  • static
    • .format : enum
    • .isDescription(obj) ⇒ Boolean
  • inner
    • ~definition

new Description([definition])

This is one of the properties that are (if provided) processed by all other properties. Any property can have an instance of Description property assigned to it with the key name description and it should be treated as something that "describes" the property within which it belongs. Usually this property is used to generate documentation and other contextual information for a property in a Collection.

Param	Type	Description
[definition]	definition | String	The content of the description can be passed as a string when it is in text/plain format or otherwise be sent as part of an object adhering to the definition structure having content and format.

Example (Add a description to an instance of Collection)

 var SDK = require('postman-collection'),
    Collection = SDK.Collection,
    Description = SDK.Description,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.description = new Description({
    content: '<h1>Hello World</h1><p>I am a Collection</p>',
    type: 'text/html'
});

// alternatively, you could also use the `.describe` method of any property to set or update the description of the
// property.
myCollection.describe('Hey! This is a cool collection.');

description.content : String

The raw content of the description

Kind: instance property of Description

description.type : String

The mime-type of the description.

Kind: instance property of Description

description.update(content, [type])

Updates the content of this description property.

Kind: instance method of Description
Todo

• parse version of description

Param	Type
content	String | definition
[type]	String

description.toString() ⇒ String

Processes the Description with the appropriate formatter as defined by Description.type

Kind: instance method of Description

description.toJSON() ⇒ Object

Creates a JSON representation of the Description (as a plain Javascript object).

Kind: instance method of Description

Description.format : enum

The default and supported description format handlers.

Kind: static enum of Description
Read only: true
Properties

Name	Type	Default	Description
"text/plain"	function		Escapes HTML characters in the description content, and returns the result.
"text/markdown"	function		Returns HTML string generated after rendering raw markdown.
"text/html"	function		Removes blacklisted HTML tags from the Description.

Description.isDescription(obj) ⇒ Boolean

Checks whether a property is an instance of Description object.

Kind: static method of Description

Param	Type
obj	*

Description~definition

Kind: inner typedef of Description
Properties

Name	Type
content	String
format	String

EventList ⇐ PropertyList

Kind: global class
Extends: PropertyList

• EventList ⇐ PropertyList
  • new EventList()
  • instance
    • .listeners(name) ⇒ Array.<event>
    • .listenersOwn(name) ⇒ Event
    • .insert(item, [before])
    • .insertAfter(item, [after])
    • .append(item)
    • .prepend(item)
    • .add(item)
    • .remove(predicate, context)
    • .clear()
    • .populate(items)
    • .repopulate(items)
    • .all() ⇒ Object
    • .one(id) ⇒ PropertyList.Type
    • .get(key) ⇒ PropertyList.Type
    • .each()
    • .filter(rule)
    • .find(rule, [context]) ⇒ Item | ItemGroup
    • .map(iterator, context)
    • .count() ⇒ Number
    • .idx(index) ⇒ PropertyList.Type
    • .indexOf(item) ⇒ Number
    • .has(item) ⇒ Boolean
    • .eachParent(iterator, [context])
    • .toObject() ⇒ Object
    • .toString() ⇒ String
  • static
    • .isEventList(obj) ⇒ boolean

new EventList()

A type of PropertyList, EventList handles resolving events from parents. If an ItemGroup contains a set of events, each Item in that group will inherit those events from its parent, and so on.

eventList.listeners(name) ⇒ Array.<event>

Returns an array of listeners filtered by the listener name

Kind: instance method of EventList

Param	Type
name	String

eventList.listenersOwn(name) ⇒ Event

Returns all events with specific listeners only within this list. Refer to listeners for procuring all inherited events

Kind: instance method of EventList

Param	Type
name	string

eventList.insert(item, [before])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index before the reference member.

Kind: instance method of EventList

Param	Type
item	PropertyList.Type
[before]	PropertyList.Type | String

eventList.insertAfter(item, [after])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index after the reference member.

Kind: instance method of EventList

Param	Type
item	PropertyList.Type
[after]	PropertyList.Type | String

eventList.append(item)

Adds or moves an item to the end of this list

Kind: instance method of EventList

Param	Type
item	PropertyList.Type

eventList.prepend(item)

Adds or moves an item to the beginning of this list

Kind: instance method of EventList

Param	Type
item	PropertyList.Type

eventList.add(item)

Add an item or item definition to this list

Kind: instance method of EventList
Todo

• - remove item from original parent if already it has a parent
• validate that the original parent's constructor matches this parent's constructor

Param	Type
item	Object | PropertyList.Type

eventList.remove(predicate, context)

Removes all elements from the PropertyList for which the predicate returns truthy.

Kind: instance method of EventList

Param	Type	Description
predicate	function | String | Type
context	Object	Optional context to bind the predicate to.

eventList.clear()

Removes all items in the list

Kind: instance method of EventList

eventList.populate(items)

Load one or more items

Kind: instance method of EventList

Param	Type
items	Object | Array

eventList.repopulate(items)

Clears the list and adds new items.

Kind: instance method of EventList

Param	Type
items	Object | Array

eventList.all() ⇒ Object

Returns a map of all items

Kind: instance method of EventList

eventList.one(id) ⇒ PropertyList.Type

Get Item in this list by ID reference. If multiple values are allowed, the last value is returned.

Kind: instance method of EventList

Param	Type
id	String

eventList.get(key) ⇒ PropertyList.Type

Get the value of an item in this list. This is similar to PropertyList.one barring the fact that it returns the value of the underlying type of the list content instead of the item itself.

Kind: instance method of EventList

Param	Type
key	String | function

eventList.each()

Iterate on each item of this list

Kind: instance method of EventList

eventList.filter(rule)

Kind: instance method of EventList

Param	Type
rule	function

eventList.find(rule, [context]) ⇒ Item | ItemGroup

Find an item within the item group

Kind: instance method of EventList

Param	Type
rule	function
[context]	Object

eventList.map(iterator, context)

Iterates over the property list.

Kind: instance method of EventList

Param	Type	Description
iterator	function	Function to call on each item.
context		Optional context, defaults to the PropertyList itself.

eventList.count() ⇒ Number

Returns the length of the PropertyList

Kind: instance method of EventList

eventList.idx(index) ⇒ PropertyList.Type

Get a member of this list by it's index

Kind: instance method of EventList

Param	Type
index	Number

eventList.indexOf(item) ⇒ Number

Find the index of an item in this list

Kind: instance method of EventList

Param	Type
item	String | Object

eventList.has(item) ⇒ Boolean

Check whether an item exists in this list

Kind: instance method of EventList

Param	Type
item	String | PropertyList.Type

eventList.eachParent(iterator, [context])

Iterates over all parents of the property list

Kind: instance method of EventList

Param	Type
iterator	function
[context]	Object

eventList.toObject() ⇒ Object

Converts a list of Properties into an object where key is _postman_propertyIndexKey and value is determined by the valueOf function

Kind: instance method of EventList

eventList.toString() ⇒ String

Adds ability to convert a list to a string provided it's underlying format has unparse function defined

Kind: instance method of EventList

EventList.isEventList(obj) ⇒ boolean

Checks if the given object is an EventList.

Kind: static method of EventList

Param
obj

Event ⇐ Property

Kind: global class
Extends: Property

• Event ⇐ Property
  • new Event(definition)
  • instance
    • .listen : String
    • .script : Script
    • .id : String
    • .name : String
    • .disabled : Boolean
    • .description : Description
    • .update(definition)
    • .describe(content, [type])
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .toJSON()
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • inner
    • ~definition

new Event(definition)

A Postman event definition that refers to an event to be listened to and a script reference or definition to be executed.

Param	Type	Description
definition	definition	Pass the initial definition of the event as the options parameter.

event.listen : String

Name of the event that this instance is intended to listen to.

Kind: instance property of Event

event.script : Script

The script that is to be executed when this event is triggered.

Kind: instance property of Event

event.id : String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Kind: instance property of Event
Note: The property can also be present in the postman_id meta in case it is not specified in the object. An auto-generated property is used wherever one is not specified

event.name : String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Kind: instance property of Event

event.disabled : Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Kind: instance property of Event
Optional:

event.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of Event
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

event.update(definition)

Update an event

Kind: instance method of Event

Param	Type
definition	definition

event.describe(content, [type])

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Kind: instance method of Event

Param	Type	Default	Description
content	String		The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
[type]	String	"text/plain"	The type of the content can be one of the values mentioned in format enumeration - namely text/plain, text/markdown or text/html.

Example (Add a description to an instance of Collection)

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

event.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of Event
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

event.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of Event

Param	Type
property	String

event.toJSON()

Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.

Kind: instance method of Event

event.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of Event

event.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of Event

Event~definition

Kind: inner typedef of Event
Properties

Name	Type	Description
listen	String	The event-name that this script will be called for. Usually either "test" or "prerequest"
script	Script | String	A Script instance that will be executed on this event. In case of a string, a new Script is created.

Example (Constructing an event)

var Event = require('postman-collection').Event,
    rawEvent = {
        listen: 'test',
        script: 'tests["response code is 401"] = responseCode.code === 401'
    },
    myEvent;
myEvent = new Event(rawEvent);

FormParam

Kind: global class

• FormParam
  • new FormParam(options)
  • instance
    • .toString() ⇒ String
  • static
    • .parse ⇒ Array
  • inner
    • ~definition

new FormParam(options)

Represents a Form Data parameter, which can exist in request body.

Param	Type	Description
options	definition	Pass the initial definition of the form data parameter.

formParam.toString() ⇒ String

Converts the FormParameter to a single param string

Kind: instance method of FormParam

FormParam.parse ⇒ Array

Parse a form data string into an array of objects, where each object contains a key and a value.

Kind: static property of FormParam
Todo

• implement this, not implemented yet.

Param	Type
formdata	String

FormParam~definition

Kind: inner typedef of FormParam
Properties

Name	Type	Description
key	String	The name ("key") of the form data parameter.
value	String	The value of the parameter.

HeaderList ⇐ PropertyList

Kind: global class
Extends: PropertyList

• HeaderList ⇐ PropertyList
  • new HeaderList()
  • instance
    • .contentSize() ⇒ Number
    • .insert(item, [before])
    • .insertAfter(item, [after])
    • .append(item)
    • .prepend(item)
    • .add(item)
    • .remove(predicate, context)
    • .clear()
    • .populate(items)
    • .repopulate(items)
    • .all() ⇒ Object
    • .one(id) ⇒ PropertyList.Type
    • .get(key) ⇒ PropertyList.Type
    • .each()
    • .filter(rule)
    • .find(rule, [context]) ⇒ Item | ItemGroup
    • .map(iterator, context)
    • .count() ⇒ Number
    • .idx(index) ⇒ PropertyList.Type
    • .indexOf(item) ⇒ Number
    • .has(item) ⇒ Boolean
    • .eachParent(iterator, [context])
    • .toObject() ⇒ Object
    • .toString() ⇒ String
  • static
    • .isHeaderList(obj) ⇒ Boolean

new HeaderList()

Contains a list of header elements

headerList.contentSize() ⇒ Number

Gets size of a list of headers excluding standard header prefix.

Kind: instance method of HeaderList

headerList.insert(item, [before])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index before the reference member.

Kind: instance method of HeaderList

Param	Type
item	PropertyList.Type
[before]	PropertyList.Type | String

headerList.insertAfter(item, [after])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index after the reference member.

Kind: instance method of HeaderList

Param	Type
item	PropertyList.Type
[after]	PropertyList.Type | String

headerList.append(item)

Adds or moves an item to the end of this list

Kind: instance method of HeaderList

Param	Type
item	PropertyList.Type

headerList.prepend(item)

Adds or moves an item to the beginning of this list

Kind: instance method of HeaderList

Param	Type
item	PropertyList.Type

headerList.add(item)

Add an item or item definition to this list

Kind: instance method of HeaderList
Todo

• - remove item from original parent if already it has a parent
• validate that the original parent's constructor matches this parent's constructor

Param	Type
item	Object | PropertyList.Type

headerList.remove(predicate, context)

Removes all elements from the PropertyList for which the predicate returns truthy.

Kind: instance method of HeaderList

Param	Type	Description
predicate	function | String | Type
context	Object	Optional context to bind the predicate to.

headerList.clear()

Removes all items in the list

Kind: instance method of HeaderList

headerList.populate(items)

Load one or more items

Kind: instance method of HeaderList

Param	Type
items	Object | Array

headerList.repopulate(items)

Clears the list and adds new items.

Kind: instance method of HeaderList

Param	Type
items	Object | Array

headerList.all() ⇒ Object

Returns a map of all items

Kind: instance method of HeaderList

headerList.one(id) ⇒ PropertyList.Type

Get Item in this list by ID reference. If multiple values are allowed, the last value is returned.

Kind: instance method of HeaderList

Param	Type
id	String

headerList.get(key) ⇒ PropertyList.Type

Get the value of an item in this list. This is similar to PropertyList.one barring the fact that it returns the value of the underlying type of the list content instead of the item itself.

Kind: instance method of HeaderList

Param	Type
key	String | function

headerList.each()

Iterate on each item of this list

Kind: instance method of HeaderList

headerList.filter(rule)

Kind: instance method of HeaderList

Param	Type
rule	function

headerList.find(rule, [context]) ⇒ Item | ItemGroup

Find an item within the item group

Kind: instance method of HeaderList

Param	Type
rule	function
[context]	Object

headerList.map(iterator, context)

Iterates over the property list.

Kind: instance method of HeaderList

Param	Type	Description
iterator	function	Function to call on each item.
context		Optional context, defaults to the PropertyList itself.

headerList.count() ⇒ Number

Returns the length of the PropertyList

Kind: instance method of HeaderList

headerList.idx(index) ⇒ PropertyList.Type

Get a member of this list by it's index

Kind: instance method of HeaderList

Param	Type
index	Number

headerList.indexOf(item) ⇒ Number

Find the index of an item in this list

Kind: instance method of HeaderList

Param	Type
item	String | Object

headerList.has(item) ⇒ Boolean

Check whether an item exists in this list

Kind: instance method of HeaderList

Param	Type
item	String | PropertyList.Type

headerList.eachParent(iterator, [context])

Iterates over all parents of the property list

Kind: instance method of HeaderList

Param	Type
iterator	function
[context]	Object

headerList.toObject() ⇒ Object

Converts a list of Properties into an object where key is _postman_propertyIndexKey and value is determined by the valueOf function

Kind: instance method of HeaderList

headerList.toString() ⇒ String

Adds ability to convert a list to a string provided it's underlying format has unparse function defined

Kind: instance method of HeaderList

HeaderList.isHeaderList(obj) ⇒ Boolean

Checks if the given object is a HeaderList

Kind: static method of HeaderList

Param	Type
obj	*

Header ⇐ Property

Kind: global class
Extends: Property

• Header ⇐ Property
  • new Header([value], [name])
  • instance
    • .key : String
    • .value : String
    • .id : String
    • .name : String
    • .disabled : Boolean
    • .description : Description
    • .toString() ⇒ String
    • .valueOf() ⇒ String
    • .update(options)
    • .describe(content, [type])
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .toJSON()
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • static
    • .parse(headerString) ⇒ Array
    • .parseSingle(header) ⇒ Object
    • .unparse(headers, [separator]) ⇒ string
    • .unparseSingle(header) ⇒ String
    • .isHeader(obj) ⇒ Boolean
    • .create([value], [name]) ⇒ Header
  • inner
    • ~definition

new Header([value], [name])

Represents an HTTP header, for requests or for responses.

Param	Type	Description
[value]	definition | String	Pass the header definition as an object or the value of the header. If the value is passed as a string, it should either be in name:value format or the second "name" parameter should be used to pass the name as string
[name]	String	optional override the header name or use when the first parameter is the header value as string.

Example (Parse a string of headers into an array of Header objects)

var Header = require('postman-collection').Header,
    headerString = 'Content-Type: application/json\nUser-Agent: MyClientLibrary/2.0\n';

var rawHeaders = Header.parse(headerString);
console.log(rawHeaders); // [{ 'Content-Type': 'application/json', 'User-Agent': 'MyClientLibrary/2.0' }]

var headers = rawHeaders.map(function (h) {
    return new Header(h);
});

assert headerString === Header.unparse(headers);

header.key : String

The header Key

Kind: instance property of Header

header.value : String

The header value

Kind: instance property of Header

header.id : String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Kind: instance property of Header
Note: The property can also be present in the postman_id meta in case it is not specified in the object. An auto-generated property is used wherever one is not specified

header.name : String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Kind: instance property of Header

header.disabled : Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Kind: instance property of Header
Overrides: disabled
Optional:

header.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of Header
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

header.toString() ⇒ String

Converts the header to a single header string

Kind: instance method of Header

header.valueOf() ⇒ String

Return the value of this header

Kind: instance method of Header

header.update(options)

Assigns the given properties to the Header

Kind: instance method of Header

Param
options

header.describe(content, [type])

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Kind: instance method of Header

Param	Type	Default	Description
content	String		The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
[type]	String	"text/plain"	The type of the content can be one of the values mentioned in format enumeration - namely text/plain, text/markdown or text/html.

Example (Add a description to an instance of Collection)

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

header.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of Header
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

header.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of Header

Param	Type
property	String

header.toJSON()

Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.

Kind: instance method of Header

header.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of Header

header.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of Header

Header.parse(headerString) ⇒ Array

Parses a multi line header string into an array of definition.

Kind: static method of Header

Param
headerString

Header.parseSingle(header) ⇒ Object

Parses a single Header.

Kind: static method of Header

Param	Type
header	String

Header.unparse(headers, [separator]) ⇒ string

Stringifies an Array or PropertyList of Headers into a single string.

Kind: static method of Header

Param	Type	Description
headers	Array | PropertyList.<Header>
[separator]	String	Specify a string for separating each header, by default, '\n', but sometimes, it might be more useful to use a carriage return ('\r\n')

Header.unparseSingle(header) ⇒ String

Unparses a single Header.

Kind: static method of Header

Param	Type
header	String

Header.isHeader(obj) ⇒ Boolean

Check whether an object is an instance of PostmanHeader.

Kind: static method of Header

Param	Type
obj	*

Header.create([value], [name]) ⇒ Header

Create a new header instance

Kind: static method of Header

Param	Type	Description
[value]	definition | String	Pass the header definition as an object or the value of the header. If the value is passed as a string, it should either be in name:value format or the second "name" parameter should be used to pass the name as string
[name]	String	optional override the header name or use when the first parameter is the header value as string.

Header~definition

Kind: inner typedef of Header
Properties

Name	Type	Description
key	String	The Header name (e.g: 'Content-Type')
value	String	The value of the header.

Example

Create a header
var Header = require('postman-collection').Header,
    header = new Header({
        key: 'Content-Type',
        value: 'application/xml'
    });

console.log(header.toString()) // prints the string representation of the Header.

ItemGroup ⇐ Property

Kind: global class
Extends: Property

• ItemGroup ⇐ Property
  • new ItemGroup([definition])
  • instance
    • .items : PropertyList.<(Item|ItemGroup)>
    • .auth : RequestAuth
    • .id : String
    • .name : String
    • .disabled : Boolean
    • .description : Description
    • .describe(content, [type])
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .toJSON()
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • static
    • .isItemGroup(obj) ⇒ Boolean
  • inner
    • ~definition

new ItemGroup([definition])

An ItemGroup represents a composite list of Item or ItemGroup. In terms of Postman App, ItemGroup represents a "Folder". This allows one to group Items into subsets that can have their own meaning. An ItemGroup also allows one to define a subset of common properties to be applied to each Item within it. For example, a test event defined on an ItemGroup is executed while testing any Item that belongs to that group. Similarly, ItemGroups can have a common {@RequestAuth} defined so that every Request, when processed, requires to be authenticated using the auth defined in the group.

Essentially, Collection too is a special type of ItemGroup ;-).

Param	Type	Description
[definition]	definition	While creating a new instance of ItemGroup, one can provide the initial configuration of the item group with the requests it contains, the authentication applied to all requests, events that the requests responds to, etc.

Example (Add a new ItemGroup to a collection instance)

var Collection = require('postman-collection').Collection,
    ItemGroup = require('postman-collection').ItemGroup,
    myCollection;

myCollection = new Collection(); // create an empty collection
myCollection.add(new ItemGroup({ // add a folder called "blank folder"
    "name": "This is a blank folder"
}));

itemGroup.items : PropertyList.<(Item|ItemGroup)>

This is a PropertyList that holds the list of Items or ItemGroups belonging to a Collection or to an ItemGroup. Operation on an individual item in this list can be performed using various functions available to a PropertyList.

Kind: instance property of ItemGroup
Example (Fetch empty ItemGroups in a list loaded from a file)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection,
    emptyGroups;
// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Filter items in Collection root that is an empty ItemGroup
emptyGroups = myCollection.items.filter(function (item) {
    return item && item.items && (item.items.count() === 0);
});

// Log the emptyGroups array to check it's contents
console.log(emptyGroups);

itemGroup.auth : RequestAuth

One can define the default authentication method required for every item that belongs to this list. Individual Requests can override this in their own definitions. More on how to define an authentication method is outlined in the RequestAuth property.

Kind: instance property of ItemGroup
Example (Define an entire ItemGroup (folder) or Collection to follow Basic Auth)

var fs = require('fs'),
    Collection = require('postman-collection').Collection,
    RequestAuth = require('postman-collection').RequestAuth,
    mycollection;

// Create a collection having two requests
myCollection = new Collection();
myCollection.items.add([
    { name: 'GET Request', request: 'https://postman-echo.com/get?auth=basic' },
    { name: 'PUT Request', request: 'https://postman-echo.com/put?auth=basic' }
]);

// Add basic auth to the Collection, to be applied on all requests.
myCollection.auth = new RequestAuth({
    type: 'basic',
    username: 'postman',
    password: 'password'
});

itemGroup.id : String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Kind: instance property of ItemGroup
Note: The property can also be present in the postman_id meta in case it is not specified in the object. An auto-generated property is used wherever one is not specified

itemGroup.name : String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Kind: instance property of ItemGroup

itemGroup.disabled : Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Kind: instance property of ItemGroup
Optional:

itemGroup.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of ItemGroup
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

itemGroup.describe(content, [type])

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Kind: instance method of ItemGroup

Param	Type	Default	Description
content	String		The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
[type]	String	"text/plain"	The type of the content can be one of the values mentioned in format enumeration - namely text/plain, text/markdown or text/html.

Example (Add a description to an instance of Collection)

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

itemGroup.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of ItemGroup
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

itemGroup.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of ItemGroup

Param	Type
property	String

itemGroup.toJSON()

Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.

Kind: instance method of ItemGroup

itemGroup.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of ItemGroup

itemGroup.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of ItemGroup

ItemGroup.isItemGroup(obj) ⇒ Boolean

Check whether an object is an instance of ItemGroup.

Kind: static method of ItemGroup

Param	Type
obj	*

ItemGroup~definition

The following defines the object (or JSON) structure that one can pass to the ItemGroup while creating a new ItemGroup instance. This is also the object structure returned when .toJSON() is called on an ItemGroup instance.

Kind: inner typedef of ItemGroup
Properties

Name	Type
item	Array.<(ItemGroupdefinition|Itemdefinition)>
auth	Array.<definition>
event	Array.<definition>

Example

{
    "name": "Echo Get Requests",
    "id": "echo-get-requests",
    "item": [{
        "request": "https://postman-echo.com/get"
    }, {
        "request": "https://postman-echo.com/headers"
    }],
    "auth": {
        "type": "basic",
        "basic": {
            "username": "jean",
            "password": "{{somethingsecret}}"
        }
    },
    "event": [{
        "listen": "prerequest",
        "script: {
            "type": "text/javascript",
            "exec": "console.log(new Date())"
        }
    }]
}

Item ⇐ Property

Kind: global class
Extends: Property

• Item ⇐ Property
  • new Item([definition])
  • instance
    • .request : Request
    • .responses : PropertyList.<Response>
    • .events : EventList
    • .id : String
    • .name : String
    • .disabled : Boolean
    • .description : Description
    • .getAuth()
    • .getEvents(name) ⇒ Array.<Event>
    • .describe(content, [type])
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .toJSON()
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • static
    • .isItem(obj) ⇒ Boolean
  • inner
    • ~definition

new Item([definition])

A Postman Collection Item that holds your request definition, responses and other stuff. An Item essentially is a HTTP request definition along with the sample responses and test scripts clubbed together. One or more of these items can be grouped together and placed in an ItemGroup and as such forms a Collection of requests.

Param	Type	Description
[definition]	definition	While creating a new instance of Item, one can provide the initial configuration of the item with the the request it sends, the expected sample responses, tests, etc

Example (Add a new Item to a folder in a collection instance)

var Collection = require('postman-collection').Collection,
    Item = require('postman-collection').Item,
    myCollection;

myCollection = new Collection({
    "item": [{
        "id": "my-folder-1",
        "name": "The solo folder in this collection",
        "item": [] // blank array indicates this is a folder
    }]
}); // create a collection with an empty folder
// add a request to "my-folder-1" that sends a GET request
myCollection.items.one("my-folder-1").add(new Item({
    "name": "Send a GET request",
    "id": "my-get-request"
    "request": {
        "url": 'https://postman-echo.com/get",
        "method": "GET"
    }
}));

item.request : Request

The instance of the Request object inside an Item defines the HTTP request that is supposed to be sent. It further contains the request method, url, request body, etc.

Kind: instance property of Item

item.responses : PropertyList.<Response>

An Item also contains a list of sample responses that is expected when the request defined in the item is executed. The sample responses are useful in elaborating API usage and is also useful for other integrations that use the sample responses to do something - say a mock service.

Kind: instance property of Item

item.events : EventList

Events are a set of of Scripts that are executed when certain activities are triggered on an Item. For example, on defining an event that listens to the "test" event, would cause the associated script of the event to be executed when the test runs.

Kind: instance property of Item
Example (Add a script to be executed on "prerequest" event)

var Collection = require('postman-collection').Collection,
    Item = require('postman-collection').Item,
    myCollection;

myCollection = new Collection({
    "item": [{
        "name": "Send a GET request",
        "id": "my-get-request"
        "request": {
            "url": 'https://postman-echo.com/get",
            "method": "GET"
        }
    }]
}); // create a collection with one request

// add a pre-request script to the event list
myCollection.items.one('my-get-request').events.add({
    "listen": "prerequest",
    "script": {
        "type": "text/javascript",
        "exec": "console.log(new Date())"
    }
});

item.id : String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Kind: instance property of Item
Note: The property can also be present in the postman_id meta in case it is not specified in the object. An auto-generated property is used wherever one is not specified

item.name : String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Kind: instance property of Item

item.disabled : Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Kind: instance property of Item
Optional:

item.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of Item
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

item.getAuth()

Fetches applicable AuthType from the current item.

returns {RequestAuthBase|undefined}

Kind: instance method of Item

item.getEvents(name) ⇒ Array.<Event>

Returns Events corresponding to a particular event name. If no name is given, returns all events. This is useful when you want to trigger all associated scripts for an event.

Kind: instance method of Item
Draft:
Todo

• decide appropriate verb names based on the fact that it gets events for a specific listener name

Param	Type	Description
name	String	one of the available event types such as test, prerequest, postrequest, etc.

Example (Get all events for an item and evaluate their scripts)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// assuming the collection has a request called "my-request-1" in root, we get it's test events
myCollection.items.one("my-request-1").getEvents("test").forEach(function (event) {
    event.script && eval(event.script.toSource());
});

item.describe(content, [type])

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Kind: instance method of Item

Param	Type	Default	Description
content	String		The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
[type]	String	"text/plain"	The type of the content can be one of the values mentioned in format enumeration - namely text/plain, text/markdown or text/html.

Example (Add a description to an instance of Collection)

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

item.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of Item
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

item.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of Item

Param	Type
property	String

item.toJSON()

Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.

Kind: instance method of Item

item.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of Item

item.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of Item

Item.isItem(obj) ⇒ Boolean

Check whether an object is an instance of PostmanItem.

Kind: static method of Item

Param	Type
obj	*

Item~definition

The following defines the object (or JSON) structure that one can pass to the Item while creating a new Item instance. This is also the object structure returned when .toJSON() is called on an Item instance.

Kind: inner typedef of Item
Todo

• add response and event to example

Properties

Name	Type	Description
request	definition	A request represents an HTTP request. If a string, the string is assumed to be the request URL and the method is assumed to be 'GET'.
responses	Array.<definition>	Sample responses for this request can be stored along with the item definition.
events	Array.<definition>	Postman allows you to configure scripts to run when specific events occur. These scripts are stored here, and can be referenced in the collection by their id.

Example

{
    "name": "Get Headers from Echo",
    "id": "my-request-1",
    "description": "Makes a GET call to echo service and returns the client headers that were sent",

    "request": {
        "url": "https://postman-echo.com/headers",
        "method": "GET"
    }
}

PropertyList

Kind: global class
Todo

• - document stuff

• PropertyList
  • instance
    • .insert(item, [before])
    • .insertAfter(item, [after])
    • .append(item)
    • .prepend(item)
    • .add(item)
    • .remove(predicate, context)
    • .clear()
    • .populate(items)
    • .repopulate(items)
    • .all() ⇒ Object
    • .one(id) ⇒ PropertyList.Type
    • .get(key) ⇒ PropertyList.Type
    • .each()
    • .filter(rule)
    • .find(rule, [context]) ⇒ Item | ItemGroup
    • .map(iterator, context)
    • .count() ⇒ Number
    • .idx(index) ⇒ PropertyList.Type
    • .indexOf(item) ⇒ Number
    • .has(item) ⇒ Boolean
    • .eachParent(iterator, [context])
    • .toObject() ⇒ Object
    • .toString() ⇒ String
  • static
    • .isPropertyList(obj) ⇒ Boolean

propertyList.insert(item, [before])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index before the reference member.

Kind: instance method of PropertyList

Param	Type
item	PropertyList.Type
[before]	PropertyList.Type | String

propertyList.insertAfter(item, [after])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index after the reference member.

Kind: instance method of PropertyList

Param	Type
item	PropertyList.Type
[after]	PropertyList.Type | String

propertyList.append(item)

Adds or moves an item to the end of this list

Kind: instance method of PropertyList

Param	Type
item	PropertyList.Type

propertyList.prepend(item)

Adds or moves an item to the beginning of this list

Kind: instance method of PropertyList

Param	Type
item	PropertyList.Type

propertyList.add(item)

Add an item or item definition to this list

Kind: instance method of PropertyList
Todo

• - remove item from original parent if already it has a parent
• validate that the original parent's constructor matches this parent's constructor

Param	Type
item	Object | PropertyList.Type

propertyList.remove(predicate, context)

Removes all elements from the PropertyList for which the predicate returns truthy.

Kind: instance method of PropertyList

Param	Type	Description
predicate	function | String | Type
context	Object	Optional context to bind the predicate to.

propertyList.clear()

Removes all items in the list

Kind: instance method of PropertyList

propertyList.populate(items)

Load one or more items

Kind: instance method of PropertyList

Param	Type
items	Object | Array

propertyList.repopulate(items)

Clears the list and adds new items.

Kind: instance method of PropertyList

Param	Type
items	Object | Array

propertyList.all() ⇒ Object

Returns a map of all items

Kind: instance method of PropertyList

propertyList.one(id) ⇒ PropertyList.Type

Get Item in this list by ID reference. If multiple values are allowed, the last value is returned.

Kind: instance method of PropertyList

Param	Type
id	String

propertyList.get(key) ⇒ PropertyList.Type

Get the value of an item in this list. This is similar to PropertyList.one barring the fact that it returns the value of the underlying type of the list content instead of the item itself.

Kind: instance method of PropertyList

Param	Type
key	String | function

propertyList.each()

Iterate on each item of this list

Kind: instance method of PropertyList

propertyList.filter(rule)

Kind: instance method of PropertyList

Param	Type
rule	function

propertyList.find(rule, [context]) ⇒ Item | ItemGroup

Find an item within the item group

Kind: instance method of PropertyList

Param	Type
rule	function
[context]	Object

propertyList.map(iterator, context)

Iterates over the property list.

Kind: instance method of PropertyList

Param	Type	Description
iterator	function	Function to call on each item.
context		Optional context, defaults to the PropertyList itself.

propertyList.count() ⇒ Number

Returns the length of the PropertyList

Kind: instance method of PropertyList

propertyList.idx(index) ⇒ PropertyList.Type

Get a member of this list by it's index

Kind: instance method of PropertyList

Param	Type
index	Number

propertyList.indexOf(item) ⇒ Number

Find the index of an item in this list

Kind: instance method of PropertyList

Param	Type
item	String | Object

propertyList.has(item) ⇒ Boolean

Check whether an item exists in this list

Kind: instance method of PropertyList

Param	Type
item	String | PropertyList.Type

propertyList.eachParent(iterator, [context])

Iterates over all parents of the property list

Kind: instance method of PropertyList

Param	Type
iterator	function
[context]	Object

propertyList.toObject() ⇒ Object

Converts a list of Properties into an object where key is _postman_propertyIndexKey and value is determined by the valueOf function

Kind: instance method of PropertyList

propertyList.toString() ⇒ String

Adds ability to convert a list to a string provided it's underlying format has unparse function defined

Kind: instance method of PropertyList

PropertyList.isPropertyList(obj) ⇒ Boolean

Checks whether an object is a PropertyList

Kind: static method of PropertyList

Param	Type
obj	*

Property ⇐ PropertyBase

Kind: global class
Extends: PropertyBase
See: Property~definition

• Property ⇐ PropertyBase
  • new Property([definition])
  • instance
    • .id : String
    • .name : String
    • .disabled : Boolean
    • .description : Description
    • .describe(content, [type])
    • .forEachParent([options], iterator)
    • .findInParents(property)
    • .toJSON()
    • .meta() ⇒ *
    • .parent() ⇒ * | undefined
  • static
    • .replaceSubstitutions(str, variables) ⇒ String
    • .replaceSubstitutionsIn(obj, variables, [mutate]) ⇒ Object
  • inner
    • ~definition

new Property([definition])

The Property class forms the base of all postman collection SDK elements. This is to be used only for SDK development or to extend the SDK with additional functionalities. All SDK classes (constructors) that are supposed to be identifyable (i.e. ones that can have a name and id) are derived from this class.

For more information on what is the structure of the definition the function parameter, have a look at definition.

This is intended to be a private class except for those who want to extend the SDK itself and add more functionalities.

Param	Type	Description
[definition]	definition	Every constructor inherited from Property is required to call the super constructor function. This implies that construction parameters of every inherited member is propagated to be sent up to this point.

property.id : String

The id of the property is a unique string that identifies this property and can be used to refer to this property from relevant other places. It is a good practice to define the id or let the system auto generate a UUID if one is not defined for properties that require an id.

Kind: instance property of Property
Note: The property can also be present in the postman_id meta in case it is not specified in the object. An auto-generated property is used wherever one is not specified

property.name : String

A property can have a distinctive and human-readable name. This is to be used to display the name of the property within Postman, Newman or other runtimes that consume collection. In certain cases, the absence of name might cause the runtime to use the id as a fallback.

Kind: instance property of Property

property.disabled : Boolean

This (optional) flag denotes whether this property is disabled or not. Usually, this is helpful when a property is part of a PropertyList. For example, in a PropertyList of Headers, the ones that are disabled can be filtered out and not processed.

Kind: instance property of Property
Optional:

property.description : Description

The description property holds the detailed documentation of any property. The description can be written in plain text, html or markdown as mentioned in format enumeration. It is recommended that this property be updated using the describe function.

Kind: instance property of Property
Overrides: description
See: Property#describe
Example (Accessing descriptions of all root items in a collection)

var fs = require('fs'), // needed to read JSON file from disk
    Collection = require('postman-collection').Collection,
    myCollection;

// Load a collection to memory from a JSON file on disk (say, sample-collection.json)
myCollection = new Collection(JSON.stringify(fs.readFileSync('sample-collection.json').toString()));

// Log the description of all root items
myCollection.item.all().forEach(function (item) {
    console.log(item.name || 'Untitled Item');
    item.description && console.log(item.description.toString());
});

property.describe(content, [type])

This function allows to describe the property for the purpose of detailed identification or documentation generation. This function sets or updates the description child-property of this property.

Kind: instance method of Property

Param	Type	Default	Description
content	String		The content of the description can be provided here as a string. Note that it is expected that if the content is formatted in any other way than simple text, it should be specified in the subsequent type parameter.
[type]	String	"text/plain"	The type of the content can be one of the values mentioned in format enumeration - namely text/plain, text/markdown or text/html.

Example (Add a description to an instance of Collection)

 var Collection = require('postman-collection').Collection,
    mycollection;

// create a blank collection
myCollection = new Collection();
myCollection.describe('Hey! This is a cool collection.');

console.log(myCollection.description.toString()); // read the description

property.forEachParent([options], iterator)

Invokes the given iterator for every parent in the parent chain of the given element.

Kind: instance method of Property
Todo

• Cache the results

Param	Type	Default	Description
[options]	Object | Boolean	{}	A set of options for the parent chain traversal.
[options.withRoot]	Boolean	false	Set to true to include the collection object as well.
iterator	function		The function to call for every parent in the ancestry chain.

property.findInParents(property)

Tries to find the given property locally, and then proceeds to lookup in each parent, going up the chain as necessary.

Kind: instance method of Property

Param	Type
property	String

property.toJSON()

Returns the JSON representation of a property, which conforms to the way it is defined in a collection. You can use this method to get the instantaneous representation of any property, including a Collection.

Kind: instance method of Property

property.meta() ⇒ *

Returns the meta keys associated with the property

Kind: instance method of Property

property.parent() ⇒ * | undefined

Returns the parent of item

Kind: instance method of Property

Property.replaceSubstitutions(str, variables) ⇒ String

This function accepts a string followed by a number of variable sources as arguments. One or more variable sources can be provided and it will use the one that has the value in left-to-right order.

Kind: static method of Property

Param	Type
str	String
variables	VariableList | Object | Array.<(VariableList|Object)>

Property.replaceSubstitutionsIn(obj, variables, [mutate]) ⇒ Object

This function accepts an object followed by a number of variable sources as arguments. One or more variable sources can be provided and it will use the one that has the value in left-to-right order.

Kind: static method of Property

Param	Type	Default
obj	Object
variables	Array.<(VariableList|Object)>
[mutate]	Boolean	false

Property~definition

Kind: inner typedef of Property
Properties

Name	Type
id	String
name	String
disabled	Boolean

ProxyConfigList ⇐ PropertyList

Kind: global class
Extends: PropertyList

• ProxyConfigList ⇐ PropertyList
  • new ProxyConfigList(populate)
  • instance
    • .resolve([url]) ⇒ definition
    • .insert(item, [before])
    • .insertAfter(item, [after])
    • .append(item)
    • .prepend(item)
    • .add(item)
    • .remove(predicate, context)
    • .clear()
    • .populate(items)
    • .repopulate(items)
    • .all() ⇒ Object
    • .one(id) ⇒ PropertyList.Type
    • .get(key) ⇒ PropertyList.Type
    • .each()
    • .filter(rule)
    • .find(rule, [context]) ⇒ Item | ItemGroup
    • .map(iterator, context)
    • .count() ⇒ Number
    • .idx(index) ⇒ PropertyList.Type
    • .indexOf(item) ⇒ Number
    • .has(item) ⇒ Boolean
    • .eachParent(iterator, [context])
    • .toObject() ⇒ Object
    • .toString() ⇒ String
  • static
    • .isProxyConfigList(obj) ⇒ Boolean

new ProxyConfigList(populate)

Param	Type	Description
populate	Array	The list of proxy objects

Example (Create a new ProxyConfigList)

var ProxyConfigList = require('postman-collection').ProxyConfigList,
    myProxyConfig = new ProxyConfigList({}, [
             {match: 'https://example.com/*',server: 'https://proxy.com',tunnel: true},
             {match: 'https://example2.com/*',server: 'http://proxy2.com'},
         ]);

proxyConfigList.resolve([url]) ⇒ definition

Matches and gets the proxy config for the particular url

Kind: instance method of ProxyConfigList
Returns: definition - The matched proxyConfig object

Param	Type	Description
[url]	String	The url for which the proxy config needs to be fetched

proxyConfigList.insert(item, [before])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index before the reference member.

Kind: instance method of ProxyConfigList

Param	Type
item	PropertyList.Type
[before]	PropertyList.Type | String

proxyConfigList.insertAfter(item, [after])

Insert an element at the end of this list. When a reference member specified via second parameter is found, the member is inserted at an index after the reference member.

Kind: instance method of ProxyConfigList

Param	Type
item	PropertyList.Type
[after]	PropertyList.Type | String

proxyConfigList.append(item)

Adds or moves an item to the end of this list

Kind: instance method of ProxyConfigList

Param	Type
item	PropertyList.Type

proxyConfigList.prepend(item)

Adds or moves an item to the beginning of this list

Kind: instance method of ProxyConfigList

Param	Type
item	PropertyList.Type

proxyConfigList.add(item)

Add an item or item definition to this list

Kind: instance method of ProxyConfigList
Todo

• - remove item from original parent if already it has a parent
• validate that the original parent's constructor matches this parent's constructor

Param	Type
item	Object | PropertyList.Type

proxyConfigList.remove(predicate, context)

Removes all elements from the PropertyList for which the predicate returns truthy.

Kind: instance method of ProxyConfigList

Param	Type	Description
predicate	function | String | Type
context	Object	Optional context to bind the predicate to.

proxyConfigList.clear()

Removes all items in the list

Kind: instance method of ProxyConfigList

proxyConfigList.populate(items)

Load one or more items

Kind: instance method of ProxyConfigList

Param	Type
items	Object | Array