new Collection(definitionopt, environmentsopt)
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
definition |
Collection.definition |
<optional> |
Pass the initial definition of the collection (name, id, etc) as
the |
environments |
Array.<Object> |
<optional> |
The collection instance constructor accepts the second parameter as an array of environment objects. Environments objects store variable definitions that are inherited by Collection#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. |
- Source:
Examples
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(pretty(myCollection));
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', JSON.stringify(myCollection, null, 2));
Extends
Members
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.
Type:
- Inherited From:
- Source:
Example
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'
});
authorizeRequestsUsing
Sets authentication method for all the items within this group
- Inherited From:
- Source:
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.
Type:
- Boolean
- Inherited From:
- Source:
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.
Type:
- Source:
Example
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)'
}
});
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
.
Type:
- String
- Inherited From:
- Source:
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.
Type:
- Inherited From:
- Source:
Example
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);
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.
Type:
- String
- Inherited From:
- Source:
protocolProfileBehavior :Object
Set of configurations used to alter the usual behavior of sending the request.
Type:
- Object
Properties:
Name | Type | Description |
---|---|---|
disableBodyPruning |
Boolean | Disable body pruning for request methods like GET, HEAD etc. |
- Inherited From:
- Source:
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.
Type:
- Source:
Example
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'
});
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.
Type:
- Source:
- See:
Methods
(static) isCollection(obj) → {Boolean}
Check whether an object is an instance of ItemGroup.
Parameters:
Name | Type | Description |
---|---|---|
obj |
* |
- Source:
Returns:
- Type
- Boolean
describe(content, typeopt)
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.
Parameters:
Name | Type | Attributes | 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 |
String |
<optional> |
"text/plain" | The type of the content. |
- Inherited From:
- Source:
Example
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
findInParents(property, customizeropt) → {*|undefined}
Tries to find the given property locally, and then proceeds to lookup in each parent,
going up the chain as necessary. Lookup will continue until customizer
returns a truthy value. If used
without a customizer, the lookup will stop at the first parent that contains the property.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
property |
String | ||
customizer |
function |
<optional> |
- Inherited From:
- Source:
Returns:
- Type
- * | undefined
forEachParent(options, iterator)
Invokes the given iterator for every parent in the parent chain of the given element.
Parameters:
Name | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object | A set of options for the parent chain traversal. Properties
|
||||||||||
iterator |
function | The function to call for every parent in the ancestry chain. |
- Inherited From:
- Source:
- To Do:
-
- Cache the results
meta() → {*}
Returns the meta keys associated with the property
- Inherited From:
- Source:
Returns:
- Type
- *
oneDeep(idOrName)
Finds the first item with the given name or id in the current ItemGroup.
Parameters:
Name | Type | Description |
---|---|---|
idOrName |
String |
- Inherited From:
- Source:
parent() → {*|undefined}
Returns the parent of item
- Inherited From:
- Source:
Returns:
- Type
- * | undefined
syncVariablesFrom(obj, trackopt) → {Object}
Using this function, one can sync the values of collection variables from a reference object.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
obj |
Object | ||
track |
Boolean |
<optional> |
- Source:
Returns:
- Type
- Object
syncVariablesTo(objopt) → {Object}
Transfer the variables in this scope to an object
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
obj |
Object |
<optional> |
- Source:
Returns:
- Type
- Object
toJSON() → {Object}
Convert the collection to JSON compatible plain object
- Overrides:
- Source:
Returns:
- Type
- Object
Type Definitions
definition
The following is the object structure accepted as constructor parameter while calling new Collection(...)
. It is
also the structure exported when Property#toJSON or Property#toObjectResolved is called on a
collection instance.
Properties:
Name | Type | Attributes | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
info |
Object |
<optional> |
The meta information regarding the collection is provided as the Properties
|
||||||||||||||||
item |
Array.<(Item.definition|ItemGroup.definition)> |
<optional> |
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 |
Variable.definition |
<optional> |
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. |
||||||||||||||||
auth |
RequestAuth.definition |
<optional> |
Collection auth allows you to define an authentication, that applies to all items in the collection. |
||||||||||||||||
event |
Array.<Event.definition> |
<optional> |
Postman allows you to configure scripts to run when specific events occur. |
||||||||||||||||
version |
String | Version.definition |
<optional> |
Version of the collection expressed in semver format. |
- Source:
- See:
-
- {ItemGroup.definition} - Since `Collection` inherits ItemGroup, the properties supported by ItemGroup are applicable as well.
Example
{
"info": {
"name": "My Postman Collection",
"version": "1.0.0"
}
"item": [{
"request": "{{base-url}}/get"
}],
"variables": [{
"id": "base-url",
"value": "https://postman-echo.com"
}]
}