Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
{ "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 eas...
Getting Started
Simplest collection that defines a request. The highlighted part is an
API definition component.
4
{
"item" : {
"name": "T...
Simplest API Definition for Multiple Requests
Multiple requests can be put in an array and the order of definition is
util...
Nesting API Multiple Definitions (folders)
Requests can be nested by putting them under "item" array within
definitions. I...
More detailed collection
definition
Saving collection related information
The entire collection can be named and versioned within the "info"
object.
8
{
"info...
Saving collection related information - expanding versions
The version specification can expand further as per semantic
ve...
Detailed definition of
requests
Advanced request definition
The request key can be expanded to contain url and other relevant information
pertaining to th...
Advanced request definition - advanced URL
The request key can be expanded to contain url can be expanded
with fine-graine...
Advanced request definition - url segments
Some APIs accept variables as part of the URL (not query string), such variable...
Advanced request definition - url query strings as array
The "query" key within url can be further expanded with descripti...
Advanced request definition - simple request method
The type of the request can be set using the method key. This can
have...
Advanced request definition - the headers array
The "headers" key is further expandable for additional configuration.
And ...
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 sen...
Sending data in requests - Other Data Modes
Specific mode of data in request can be provided by expanding data
to an objec...
Sending data in requests - URL Encoded Form Data
The key-value pairs of form data and URL encoded data can be set as
separ...
Sending data in requests - Multi-part Data
Multipart data can be sent just like form data by changing the mode to
"multipa...
Specifying scripts within
requests
Scripting and defining Tests - events inside request
The events object holds individual scripts to be executed as prerequi...
Scripting and defining Tests - referring to a global script
Scripts can be defined globally and then referred from request...
Scripting and defining Tests - structure of a script definition
The script definitions, whether within request or as globa...
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
correspondin...
What a sample request looks like
The contents/structure of the sample.request object is same as the
parent item.request's ...
What a sample response looks like
Response from server can be saved and associated with the sample request by the
addition...
Saving multiple sample requests and responses
Multiple sample requests and responses can be saved as an array of
objects w...
Defining reusable
variables within collection
Environment Variables within collections
These variables can be re-used throughout the collection. They are scoped around
...
Environment Variables within collections - scoping
These variables can be re-used throughout the collection. They are
scop...
Documenting your
Collection
Providing extended description to components
The key "description", describes that object. It is useful for elaborating
do...
Providing extended description to components
Subsequently, "description" key placed within any component,
describes that c...
Expandable description object
The "description" key can always be expanded to an object and provide
additional information...
Expandable description object - versioning
As part of description, one can provide the version related information.
38
{
"...
Meta information within
Collection
Extending collection using Meta Information
Any key starting with underscore (_) is a user-defined meta information. These...
Meta can be anywhere
Meta definitions can be placed anywhere and they will be available while accessing
that context. The ...
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 wr...
Supercharge your API workflow
http://www.getpostman.com/
help@getpostman.com
@postmanclient
Nächste SlideShare
Wird geladen in …5
×

Postman Collection Format v2.0 (pre-draft)

87.369 Aufrufe

Veröffentlicht am

A step-by-step guide to Postman Collection format v2.0

Veröffentlicht in: Technologie

Postman Collection Format v2.0 (pre-draft)

  1. 1. { "postman": "collection" } Proposal for version 2.0
  2. 2. 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
  3. 3. Getting Started
  4. 4. 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
  5. 5. 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" }] }
  6. 6. 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" }] }] }
  7. 7. More detailed collection definition
  8. 8. 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" : […] }
  9. 9. Saving collection related information - expanding versions The version specification can expand further as per semantic versioning specs. 9 { "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" : […] }
  10. 10. Detailed definition of requests
  11. 11. 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" : [{ "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" } }, …] }
  12. 12. Advanced request definition - advanced URL The request key can be expanded to contain url can be expanded with fine-grained definition. 12 { "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", … } }, …] }
  13. 13. 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": { "protocol": "https", "domain": "example.com", "segments": ["api", { "type": "string", "value": "hello" }, { "type": "string", "value": "world" }, …], "port": "8080", "query": "key1=value1&key2=value2" } "method": "GET", … } }, …] }
  14. 14. 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" : [{ "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", … } }, …] }
  15. 15. 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" : [{ "name": "This is a request", "request": { "url": {…}, "method": "GET", "headers": "…", "data": "…" } }, …] }
  16. 16. 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" : [{ "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" } }, …] }
  17. 17. Sending data as part of request
  18. 18. 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" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": "This is my raw data and it can be anything within a string!" } }, …] }
  19. 19. 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" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": { "content": "01010100011100010100111", "mode": "binary" }, } }, …] }
  20. 20. 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" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": { "content": [{"key1": "value1"}, {"key2", "value2"}, …], "mode": "form" }, } }, …] }
  21. 21. 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" : [{ "name": "This is a request", "request": { "url": {…}, "method": "POST", "header": […], "data": { "content": [{"key1": "value1"}, {"key2", "value2"}, …], "mode": "multipart" }, } }, …] }
  22. 22. Specifying scripts within requests
  23. 23. 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" : [{ "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": {…} } } }] }
  24. 24. 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" : [{ "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}}" } } }] }
  25. 25. 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;" } } } }] }
  26. 26. Saving sample request and response
  27. 27. 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" : [{ "name": "This is a request", "request": {…}, "sample": { "name": "Sample request to the server", "request": {…}, "response": {…}, "environment": [{…}, …] } }, …] }
  28. 28. 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" : [{ "name": "This is a request", "url": {…}, "request": {…}, "sample": { "name": "My sample request", "request": { "name": "The request", "url": {…}, "method": "POST", "headers": […], "data": […] } } }, …] }
  29. 29. 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" : [{ "name": "This is a request", "url": {…}, "request": {…}, "sample": { "name": "…", "request": {…}, "environment": [], "response": { "status": "…", "headers": […], "data": "…" } } }, …] }
  30. 30. 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" : [{ "name": "This is a request", "url": {…}, "request": {…}, "sample": [{…}, {…}, …] }, …] }
  31. 31. Defining reusable variables within collection
  32. 32. 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" } } }, …] }
  33. 33. 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", … } }, …] }
  34. 34. Documenting your Collection
  35. 35. Providing extended description to components The key "description", describes that object. It is useful for elaborating documentations or usage. 35 { "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" : […] }
  36. 36. Providing extended description to components Subsequently, "description" key placed within any component, describes that component. 36 { "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!" }] }
  37. 37. 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": { "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" : […] }
  38. 38. Expandable description object - versioning As part of description, one can provide the version related information. 38 { "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" : […] }
  39. 39. Meta information within Collection
  40. 40. 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": { "name": "My collection of APIs", "_myspace": "Store additional information", "_postman": { "info": "_postman is a reserved keyword", "timestamp": 1421052080647, "synced": false, "remoteLink": "" } }, "item" : [{ "request": {…} }, …] }
  41. 41. 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": { "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": {…} }, …] }
  42. 42. Salient features of new Collection format
  43. 43. • 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.
  44. 44. Supercharge your API workflow http://www.getpostman.com/ help@getpostman.com @postmanclient

×