Postman Collection Format v2.0 (pre-draft)

{ "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
2

Simplest collection that defines a request. The highlighted part is an
API definition component.
4
{
"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.
8
{
"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.
9
{
"info": {
"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.)
11
{
"info": {…},
"item" : [{
"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.
12
{
"info": {…},
"item" : [{
"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.
13
{
"info": {…},
"item" : [{ …
"request": {
"url": {
"segments": ["api", {
"type": "string",
"value": "hello"
}, {
"type": "string",
"value": "world"
}, …],
"port": "8080",
"query": "key1=value1&key2=value2"
}
}
}, …]
}

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!
14
{
"info": {…},
"item" : [{
"request": {
"url": {
"segments": […]
"port": "8080",
"query": [{
"key": "query1",
"value": "value1",
"description": "This describes this key for documentation, usage"
}, …]
},
}
}, …]
}

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
15
{
"info": {…},
"item" : [{
"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!
16
{
"info": {…},
"item" : [{
"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.
18
{
"info": {…},
"item" : [{
"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".
19
{
"info": {…},
"item" : [{
"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.
20
{
"info": {…},
"item" : [{
"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"
21
{
"info": {…},
"item" : [{
"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.
23
{
"info": {…},
"item" : [{
"request": {
"url": {…},
"method": "POST",
"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.
24
{
"info": {…},
"scripts": [
{ "id": "my-script-1", …},
{ "id": "my-script-2", …}, …
],
"item" : [{
"request": {
"url": {…},
"method": "POST",
"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.
25
{
"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.
27
{
"info": {…},
"item" : [{
"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.
28
{
"info": {…},
"item" : [{
"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.
29
{
"info": {…},
"item" : [{
"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.
30
{
"info": {…},
"item" : [{
"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.
32
{
"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.
33
{
"info": {…},
"variables": [{…}, {…} …],
"item" : [{
"name": "This is a {{var1}} request",
"request": {
"url": "http://example.com/api/{{var1}}",
"headers": "key1=value1&key2=value2&{{var2}}=value3", …
}
}, …]
}

Providing extended description to components
The key "description", describes that object. It is useful for elaborating
documentations or usage.
35
{
"info": {
"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.
36
{
"info": {
"description": "This is a collection of example APIs"
},
"item" : [{
"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.
37
{
"info": {
"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.
38
{
"info": {
"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.
40
{
"info": {
"_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.
41
{
"info": {
"_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

Postman Collection Format v2.0 (pre-draft)

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Similar a Postman Collection Format v2.0 (pre-draft)

Similar a Postman Collection Format v2.0 (pre-draft) (20)

Último

Último (20)

Postman Collection Format v2.0 (pre-draft)