Concepts

This is a gentle introduction to the sort of functionality that the SDK provides.

Collection Hierarchy

At a very high level, Collections are organized in the following way:

                                              +------------+
                   +--------------------------+ Collection +------------------------+
                   |                          +------+-----+                        |
                   |                                 |                              |
                   |                                 |                              |
           +-------v---------+                    +--v---+                    +-----v-----+
           |ItemGroup(Folder)|         +----------+ Item +------------+       |Information|
           +-+-----------+---+         |          +---+--+            |       +-----------+
             |           |             |              |               |
    +--------v--+    +---v--+     +----v----+    +----v------+    +---v----+
    | ItemGroup |    | Item |     | Request |    | Responses |    | Events |
    +-----------+    +------+     +---------+    +-----------+    +--------+

Collection

A collection can contain a number of Items, ItemGroups and can have a single information block.

E.g: A very simple Collection

{
    "information": {
        "name": "My Collection",
        "version": "v2.0.0",
        "description": "This is a demo collection.",
        "schema": "https://schema.getpostman.com/json/collection/v2.0.0/"
    },
    "item": []
}

The "schema" property is required, and must be set to the proper URL as above. The "item" array contains Folders (ItemGroups) or Items.

Item

An Item is the basic building block for a collection. It represents an HTTP request, along with the associated metadata.

E.g: A simple Item

{
    "id": "my-first-item",
    "name": "My First Item",
    "description": "This is an Item that contains a single HTTP GET request. It doesn't really do much yet!",
    "request": "http://echo.getpostman.com/get",
    "response": []
}

An Item can have multiple saved responses, which are stored in the response array. Response is further elaborated below. While we've defined a very simple request above, it can become really complicated, as you'll soon see!

ItemGroup (Folder)

An ItemGroup is a simple container for Items. Literally, a Collection is just an ItemGroup with a special information block.

E.g: An ItemGroup with two Items

{
    "id": "my-first-itemgroup",
    "name": "First Folder",
    "description": "This ItemGroup (Folder) contains two Items.",
    "item": [
        {
            "id": "1",
            "name": "Item A",
            "request": "http://echo.getpostman.com/get"
        },
        {
            "id": "2",
            "name": "Item B",
            "request": "http://echo.getpostman.com/headers"
        }
    ]
}

The item array above contains the Items in this ItemGroup.

Request

A Request represents an HTTP request. Usually, a Request belongs to an Item. Requests can be specified as a string (check the example above) or as a JSON Object. If specified as a string, it is assumed to be a GET request.

E.g: A mildly complicated Request

{
    "description": "This is a sample POST request",
    "url": "https://echo.getpostman.com/post",
    "method": "POST",
    "header": [
        {
            "key": "Content-Type",
            "value": "application/json"
        },
        {
            "key": "Host",
            "value": "echo.getpostman.com"
        }
    ],
    "body": {
        "mode": "urlencoded",
        "urlencoded": [
            {
                "key": "my-body-variable",
                "value": "Something Awesome!"
            }
        ]
    }
}

For more on request bodies, check the API documentation: RequestBody

E.g: A simple request with Authentication information

{
    "url": "https://echo.getpostman.com/basic-auth",
    "method": "GET",
    "auth": {
        "type": "basic",
        "basic": {
            "username": "fred",
            "password": "hunter2"
        }
    }
}

The SDK supports a number of auth types, refer to the API documentation: RequestAuth

Events

The SDK currently supports two events:

1. Test Script: test You can associate a test script with an Item. The test script is usually executed after the actual HTTP request is sent, and the response is received.

2. Pre-Request Script: prerequest Pre-Request scripts are usually executed before the HTTP request is sent.

E.g: An Item with Events

{
    "id": "evented-item",
    "name": "Item with Events",
    "description": "This is an Item that contains `test and `prerequest` events.",
    "request": "http://echo.getpostman.com/get",
    "event": [
        {
            "listen": "prerequest",
            "script": {
                "type": "text/javascript",
                "exec": "console.log('We are in the pre-request script, the request has not run yet!')"
            }
        },
        {
            "listen": "test",
            "script": {
                "type": "text/javascript",
                "exec": "console.log('We are using the test script now, and the request was already sent!')"
            }
        }
    ]
}