Convert a Postman collection to .http files
Postman collections are JSON documents stored in a Postman workspace. Converting them to .http files puts your requests in the repository next to the code they test, where they are reviewed in pull requests and shared through git instead of a cloud account. Plainwire imports Postman v2.0 and v2.1 collections and Postman environments in one step; this page also shows how every part maps, so you can check the result or convert by hand.
No VS Code at hand? Paste your collection into the online Postman to .http converter. It runs in your browser with the same code as Plainwire; nothing is uploaded.
Step 1: export from Postman
- Collection. In Postman, open the … menu next to the collection, choose Export, select Collection v2.1 and save the
.jsonfile. - Environments. Open Environments, use the … menu on each environment and choose Export. Exported environment files can contain real tokens and passwords, so do not commit them as they are.
A shortened v2.1 collection looks like this:
{
"info": {
"name": "Shop API",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"auth": {
"type": "bearer",
"bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ]
},
"variable": [ { "key": "apiVersion", "value": "v2" } ],
"item": [
{
"name": "Orders",
"item": [
{
"name": "List orders",
"request": {
"method": "GET",
"header": [ { "key": "Accept", "value": "application/json" } ],
"url": {
"raw": "{{baseUrl}}/{{apiVersion}}/orders?status=open",
"host": [ "{{baseUrl}}" ],
"path": [ "{{apiVersion}}", "orders" ],
"query": [ { "key": "status", "value": "open" } ]
}
}
},
{
"name": "Create order",
"request": {
"method": "POST",
"header": [],
"body": {
"mode": "raw",
"raw": "{\n \"sku\": \"TSHIRT-M\",\n \"quantity\": 2\n}",
"options": { "raw": { "language": "json" } }
},
"url": "{{baseUrl}}/{{apiVersion}}/orders"
}
}
]
}
]
}
Step 2: import with Plainwire
- Install Plainwire from the latest
.vsixrelease (install steps). - Open your project, run Plainwire: Import Postman Collection… from the Command Palette (or the Import Postman Collection button in the empty Plainwire sidebar, or the … menu of the Requests view) and pick the exported file.
- Select the collection file, then the environment files. Requests are written as
.httpfiles in your workspace and environments go intohttp-client.env.json. - Move secrets to
http-client.private.env.json, add it to.gitignore, send a request to check, and commit.
The collection above becomes something like this (exact formatting may differ):
@apiVersion = v2
### List orders
GET {{baseUrl}}/{{apiVersion}}/orders?status=open
Accept: application/json
Authorization: Bearer {{token}}
### Create order
POST {{baseUrl}}/{{apiVersion}}/orders
Authorization: Bearer {{token}}
Content-Type: application/json
{
"sku": "TSHIRT-M",
"quantity": 2
}
Note how the collection-level bearer auth became an Authorization header on each request. The .http format has no inheritance, so auth that Postman inherits from the collection or a folder is written out per request.
Field mapping
| Postman | In a .http file |
|---|---|
Collection info.name | File or folder name |
Folder (an item with its own item list) | A separate .http file; nested folders become subfolders (Pets/Admin.http) |
Request name | ### Title line |
request.method, url.raw | Request line |
url.query | Query string, or ? / & continuation lines |
Path variable :id with url.variable | {{id}} in the URL plus @id = 42 |
header | Name: value lines; disabled headers can be left as # comments |
body.mode: raw (JSON, text, XML) | Body text, with a matching Content-Type |
body.mode: urlencoded | a=1&b=2 with application/x-www-form-urlencoded |
body.mode: graphql | A GraphQL request: X-REQUEST-TYPE: GraphQL, the query, a blank line, the variables JSON (format) |
auth bearer / basic (also inherited) | Authorization: Bearer … / Authorization: Basic … |
Collection variable | @name = value at the top of the file |
| Environment | Entry in http-client.env.json |
Test scripts (event, listen: test) | Common snippets (pm.response.to.have.status, response time, headers, jsonData.x equals, body includes, length) become # @assert lines (0.2+). Since 0.13, any other test script is kept whole as a > {% %} block that runs with a pm API |
| Pre-request scripts | Since 0.13, kept as a < {% %} block above the request (what runs) |
| Folder- and collection-level scripts | Not imported; listed as warnings |
Environments to http-client.env.json
Each exported Postman environment is a separate file:
{
"name": "Staging",
"values": [
{ "key": "baseUrl", "value": "https://staging.example.com", "type": "default", "enabled": true },
{ "key": "token", "value": "", "type": "secret", "enabled": true }
],
"_postman_variable_scope": "environment"
}
All environments are combined into one http-client.env.json, keyed by environment name. Secrets go into the private file with the same keys:
// http-client.env.json (commit)
{
"local": { "baseUrl": "http://localhost:3000" },
"staging": { "baseUrl": "https://staging.example.com" }
}
// http-client.private.env.json (gitignore)
{
"local": { "token": "dev-token" },
"staging": { "token": "replace-me" }
}
Comments are shown above only to label the two files; JSON files themselves should not contain them.
Dynamic variables
Some Postman dynamic variables share a name with .http system variables; others need a change or have no equivalent.
| Postman | .http |
|---|---|
{{$guid}} | {{$guid}} (same) |
{{$timestamp}} | {{$timestamp}} (same) |
{{$randomInt}} (0 to 1000) | {{$randomInt 0 1001}}; bounds are required |
{{$isoTimestamp}} | {{$datetime iso8601}} |
{{$randomEmail}}, {{$randomFirstName}} and other fake-data variables | No equivalent; replace with fixed test values or file variables |
Scripts and tests
Since 0.13, request-level Postman scripts are kept in the .http file and run with a Postman-compatible pm API: pm.test, the common pm.expect chain, pm.response, and pm.environment / pm.collectionVariables / pm.globals, whose set makes the value available to later requests as {{name}}. pm.sendRequest, require(), pm.visualizer, pm.cookies, pm.vault and async tests are not supported, and the importer warns when a script uses them. The full list is in scripts in .http files.
The most common script, saving a token from a login response, can also be replaced by request chaining, which needs no script and sends the login request for you when needed:
### Login
# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json
{ "email": "{{user}}", "password": "{{password}}" }
### Profile (uses the token from the login response)
GET {{baseUrl}}/me
Authorization: Bearer {{login.response.body.$.access_token}}
Test scripts made only of common checks (pm.response.to.have.status, response time, headers, jsonData.x equals) become # @assert lines, which are shorter to read and also work as comments in other clients.
Checklist
- Every environment variable your requests use exists in each environment.
- No secrets in
http-client.env.jsonor in the.httpfiles. - Path variables (
:id) were turned into{{id}}. - One request per environment sends successfully.
Related: cURL to .http, .http syntax cheat sheet.