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

  1. Collection. In Postman, open the … menu next to the collection, choose Export, select Collection v2.1 and save the .json file.
  2. 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

  1. Install Plainwire from the latest .vsix release (install steps).
  2. 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.
  3. Select the collection file, then the environment files. Requests are written as .http files in your workspace and environments go into http-client.env.json.
  4. 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

PostmanIn a .http file
Collection info.nameFile 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.rawRequest line
url.queryQuery string, or ? / & continuation lines
Path variable :id with url.variable{{id}} in the URL plus @id = 42
headerName: value lines; disabled headers can be left as # comments
body.mode: raw (JSON, text, XML)Body text, with a matching Content-Type
body.mode: urlencodeda=1&b=2 with application/x-www-form-urlencoded
body.mode: graphqlA 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
EnvironmentEntry 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 scriptsSince 0.13, kept as a < {% %} block above the request (what runs)
Folder- and collection-level scriptsNot 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 variablesNo 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

Related: cURL to .http, .http syntax cheat sheet.