{ "postman": "collection" }

Proposal for version 2.0

It is a minimalist free-form guideline for defining APIs

Can be easily extended for applications

Has NodeJS module for easy manipulation

Works with every aspect of API management

Underlying structure is JSON

Human readable and writeable

Highly portable

Getting Started

Simplest collection that defines a request. The highlighted part is an API definition component.

{ "item" : { "name": "This is a request", "request": "http://myapi.com/api" }}

Simplest API Definition

Simplest API Definition for Multiple Requests

Multiple requests can be put in an array and the order of definition is utilised for all purposes of ordering. API definition component always reside inside the "item" object or array.

{ "item" : [{ "name": "This is request one", "request": "http://myapi.com/api/1" }, { "name": "This is a request two", "request": "http://myapi.com/api/2" }]}

Nesting API Multiple Definitions (folders)

Requests can be nested by putting them under "item" array within definitions. In such cases, the parent is no longer treated as a request and it's url, request, etc fields are ignored.

{ "item" : [{ "item": [{ "name": "This is request one dot one", "request": "http://myapi.com/api/1.1" }, { "name": "This is a request one dot two", "request": "http://myapi.com/api/1.2" }] }]}

More detailed collection definition

Saving collection related information

The entire collection can be named and versioned within the "info" object.

{ "info": { "name": "My collection of APIs", "version": "1.2.3-alpha.1+sha1", "schema": "https://schema.getpostman.com#2.0.0" }, "item" : […]}

Saving collection related information - expanding versions

The version specification can expand further as per semantic versioning specs.

{ "info": { "name": "My collection of APIs", "version": { "major": "1", "minor": "2", "patch": "3", "identifier": "beta.1", "meta": "git:ddfaa6" }, "schema": "https://schema.getpostman.com#2.0.0" }, "item" : […]}

Detailed definition of requests

Advanced request definition

The request key can be expanded to contain url and other relevant information pertaining to the request. The raw request headers and data can be sent as text in its simplest form (we can expand these to customise further.)

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": "https://example.com:8080/api/hello/world?key=value", "method": "GET", "header": "Accept-Charset: iso-8859-5, unicode-1-1; q=0.8", "data": "field1=value1&field2=value2" } }, …]}

Advanced request definition - advanced URL

The request key can be expanded to contain url can be expanded with fine-grained definition.

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": { "protocol": "https", "domain": "example.com", "segments": "api/hello/world", "port": "8080", "query": "key1=value1&key2=value2" }, "method": "GET", … } }, …]}

Advanced request definition - url segments

Some APIs accept variables as part of the URL (not query string), such variables become part of the segments array. These can be type-restricted and documented.

{ "info": {…}, "item" : [{ … "request": { "url": { "protocol": "https", "domain": "example.com", "segments": ["api", { "type": "string", "value": "hello" }, { "type": "string", "value": "world" }, …], "port": "8080", "query": "key1=value1&key2=value2" } "method": "GET", … } }, …]}

Advanced request definition - url query strings as array

The "query" key within url can be further expanded with description of the key. As such descriptions can be further expanded too!

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": { "protocol": "https", "domain": "example.com",

"segments": […] "port": "8080", "query": [{ "key": "query1",

"value": "value1", "description": "This describes this key for documentation, usage"

}, …] },

"method": "GET", … }

}, …]}

Advanced request definition - simple request method

The type of the request can be set using the method key. This can have values such as GET, POST, PUT, etc

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "GET", "headers": "…", "data": "…"

} }, …]

}

Advanced request definition - the headers array

The "headers" key is further expandable for additional configuration. And yes… the "description" snippet is available here too!

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": [{ "key": "Accept-Charset", "value": "iso-8859-5, unicode-1-1; q=0.8", "description": "Only character sets acceptable for the response" }, …], "data":"field1=value1&field2=value2" } }, …]}

Sending data as part of request

Sending data in requests - RAW

The "data" key within "request" contains the data to be sent. When set as string, it is sent as pure RAW data.

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": "This is my raw data and it can be anything within a string!" } }, …]}

Sending data in requests - Other Data Modes

Specific mode of data in request can be provided by expanding data to an object having "content" and "mode".

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": { "content": "01010100011100010100111", "mode": "binary" }, } }, …]}

Sending data in requests - URL Encoded Form Data

The key-value pairs of form data and URL encoded data can be set as separate modes and passed as array in "content" key.

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": { "content": [{"key1": "value1"}, {"key2", "value2"}, …], "mode": "form" }, } }, …]}

Sending data in requests - Multi-part Data

Multipart data can be sent just like form data by changing the mode to "multipart"

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": { "content": [{"key1": "value1"}, {"key2", "value2"}, …], "mode": "multipart" }, } }, …]}

Specifying scripts within requests

Scripting and defining Tests - events inside request

The events object holds individual scripts to be executed as prerequisite, test and teardown. You can also provide an array of scripts to be executed in order.

{ "info": {…}, "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": "Accept-Charset: iso-8859-5, unicode-1-1; q=0.8", "data": "field1=value1&field2=value2", "events": { "setup": {…}, "test": [{…}, {…}, …], "teardown": {…} } } }]}

Scripting and defining Tests - referring to a global script

Scripts can be defined globally and then referred from requests using the name key of the defined script. You can also pass variables to the globally defined scripts.

{ "info": {…}, "scripts": [ { "id": "my-script-1", …}, { "id": "my-script-2", …}, … ], "item" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": "Accept-Charset: iso-8859-5, unicode-1-1; q=0.8", "data": "field1=value1&field2=value2", "events": { "setup": "my-script-1", "test": [{…},"my-script-2", …], "teardown": "my-script-2 {{var1}} {{var2}}" } } }]}

Scripting and defining Tests - structure of a script definition

The script definitions, whether within request or as global definition, has a name, type and the script body as "exec" key. "id" field in any script allows referencing to that script when placed in scripts array of collection.

{ "info": {…}, "item" : [{ … "request": { … "events": { "setup": { "id": "identification-of-script-for-referencing", "type": "text/javascript", "exec": "/* your script body */ return true;" } } } }]}

Saving sample request and response

Saving sample request and response

A sample request is nothing more than a copy of the request object and its corresponding server response stored in the sample object. The resolved value of the variables available during sending the request can also be stored as the environment object.

{ "info": {…}, "item" : [{ "name": "This is a request", "request": {…}, "sample": { "name": "Sample request to the server", "request": {…}, "response": {…}, "environment": [{…}, …] } }, …]}

What a sample request looks like

The contents/structure of the sample.request object is same as the parent item.request's expanded form.

{ "info": {…}, "item" : [{ "name": "This is a request", "url": {…}, "request": {…}, "sample": { "name": "My sample request", "request": { "name": "The request", "url": {…}, "method": "POST", "headers": […], "data": […] } } }, …]}

What a sample response looks like

Response from server can be saved and associated with the sample request by the additional response key. Response contains the response status code, the headers from server and the data sent by the server.

{ "info": {…}, "item" : [{ "name": "This is a request", "url": {…}, "request": {…}, "sample": { "name": "…", "request": {…}, "environment": [], "response": { "status": "…", "headers": […], "data": "…" } } }, …]}

Saving multiple sample requests and responses

Multiple sample requests and responses can be saved as an array of objects within the sample property of the api definition.

{ "info": {…}, "item" : [{ "name": "This is a request", "url": {…}, "request": {…}, "sample": [{…}, {…}, …] }, …]}

Defining reusable variables within

collection

Environment Variables within collections

These variables can be re-used throughout the collection. They are scoped around the requests of its sibling item and downward. A variable name always starts with an alphabet.

{ "info": {…}, "variables": [{ "id": "var1", "value": "value1", "type": "string" }, { "id": "var2", "value": "value2", "type": "string" }, …], "item" : [{ "name": "This is a {{var1}} request", "request": { "url": { …, "domain": "example.com/api/{{var1}}", "query": "key1=value1&key2=value2&{{var2}}=value3" } } }, …]}

Environment Variables within collections - scoping

These variables can be re-used throughout the collection. They are scoped around the requests of its sibling item and downward.

{ "info": {…}, "variables": [{…}, {…} …], "item" : [{ "name": "This is a {{var1}} request", "request": { "url": "http://example.com/api/{{var1}}", "headers": "key1=value1&key2=value2&{{var2}}=value3", … } }, …]}

Documenting your Collection

Providing extended description to components

The key "description", describes that object. It is useful for elaborating documentations or usage.

{ "info": { "name": "My collection of APIs", "version": "1.2.3-alpha.1+sha1", "schema": "https://schema.getpostman.com#2.0.0", "description": "This is a collection of example APIs" }, "item" : […]}

Providing extended description to components

Subsequently, "description" key placed within any component, describes that component.

{ "info": { "name": "My collection of APIs", "version": "1.2.3-alpha.1+sha1", "schema": "https://schema.getpostman.com#2.0.0", "description": "This is a collection of example APIs" }, "item" : [{ "name": "This is a request", "request": "http://myapi.com/api" "description": "This request does nothing!" }]}

Expandable description object

The "description" key can always be expanded to an object and provide additional information to the nature of the description content.

{ "info": { "name": "My collection of APIs", "version": "1.2.3-alpha.1+sha1", "schema": "https://schema.getpostman.com#2.0.0", "description": { "content": "<p>This is a collection of example APIs</p>", "format": "HTML" } }, "item" : […]}

Expandable description object - versioning

As part of description, one can provide the version related information.

{ "info": { "name": "My collection of APIs", "version": "1.2.3-alpha.1+sha1", "schema": "https://schema.getpostman.com#2.0.0", "description": { "content": "<p>This is a collection of example APIs</p>", "format": "HTML", "since": "2.0.0", "deprecated": "3.0.0" } }, "item" : […]}

Meta information within Collection

Extending collection using Meta Information

Any key starting with underscore (_) is a user-defined meta information. These are not collection variables as they are not available during request runtime, but are available while collection is being parsed and accessed programmatically.

{ "info": { "name": "My collection of APIs", "_myspace": "Store additional information", "_postman": { "info": "_postman is a reserved keyword", "timestamp": 1421052080647, "synced": false, "remoteLink": "" } }, "item" : [{ "request": {…} }, …]}

Meta can be anywhere

Meta definitions can be placed anywhere and they will be available while accessing that context. The variable name proceeding underscore creates a secure namespace for the data to be safely read from and written to.

{ "info": { "name": "My collection of APIs", "_myspace": "Store additional information", "_postman": { "info": "_postman is a reserved keyword", "timestamp": 1421052080647, "synced": false, "remoteLink": "" } }, "item" : [{ "request": { "url": "http://www.example.com/api/v1/data", "method": "GET", "_yourspace": "Some meta stored in separate namespace" }, "_myspace": {…} }, …]}

Salient features of new Collection format

• Intuitive schema with negligible learning curve that can get one started in a matter of minutes.

• Human readable and writeable because it uses minimum referencing or computation.

• Flexible documentation for every aspect of the format, supporting modelling, definition, testing, documentation and (possibly) deployment.

• Namespaced meta allows the collection to easily store (and carry) data within any environment/toolchain.

• Node module to access and manipulate the collection makes it very easy and reliable for adoption within systems.

• Every aspect is commutative, recursive and self-contained to allow backward-compatible upgrades to the format.

Supercharge your API workflow

http://www.getpostman.com/help@getpostman.com@postmanclient