Creating Targets

Please start by browsing for available targets and inspect each implementation.

a target is a simple module with a constructor that accepts two parameters: source and options, where source is the HAR Object to process, and options is an optional object with any target specific flags (used for customizing the output).

Output Targets

output targets are simple modules that expose a constructor (which handles the transformation) and a meta info property.

module.exports = function (opts) {
  // optionally process `opts` object for target specific configuration
  // 
  // process `this.source` object
  // 
  // return processed output as string
};

module.exports.info = {
  key: 'curl',
  title: 'cURL',
  link: 'http://curl.haxx.se/',
  description: 'curl is a command line tool and library for transferring data with URL syntax',
  extname: '.sh'
};

Conversion Rules

1. start by reading an understanding the HAR format.
2. utilize utility properties created for convenience (source.headersObj, source.uriObj etc ...) see below for mode details
3. follow the guidelines below for best practices and consistency.

Guidelines

Using the following example of a request object, HTTP Snippet will pre-process data and create some additional properties:

property	description
source.fullUrl	the full & final url, including all query string values
source.uriObj	the url parsed with url.parse(). compatible with url.format
source.queryObj	a key => value pair, "normalized" version of source.queryString, adds additional query string values from the source.url
source.headersObj	a key => value pair, "normalized" version of source.headers, header names are lowercased
source.allHeaders	same as source.headersObj but with cookies header and populated from source.cookies array
source.postData.jsonObj	the parsed value of source.postData.text, only for source.postData.mimeType = application/json (or equivalent mimeTypes)
source.postData.paramsObj	a key => value pair, "normalized" version of source.postData.params, only for source.postData.mimeType = application/x-www-form-urlencoded

Sample Incoming Request Object

{
  method: 'POST',
  url: 'http://mockbin.com/har?key=value',
  httpVersion: 'HTTP/1.1',
  queryString: [
    { name: 'foo', value: 'bar' },
    { name: 'foo', value: 'baz' },
    { name: 'baz', value: 'abc' }
  ],
  headers: [
    { name: 'Accept', value: 'application/json' },
    { name: 'Content-Type', value: 'application/x-www-form-urlencoded' }
  ],

  cookies:  [
    { name: 'foo', value: 'bar' },
    { name: 'bar', value: 'baz' }
  ],

  postData: {
    mimeType: 'application/x-www-form-urlencoded',
    params: [
      { name: 'foo', value: 'bar' },
      { name: 'foo', value: 'baz' },
      { name: 'baz', value: 'abc' }
    ]
  }
}

Processed Source Object

{
  method: 'POST',

  // the base url value stripped of any the query string
  url: 'http://mockbin.com/har',

  // the full & final url, including all query string values
  fullUrl: 'http://mockbin.com/har?foo=bar&foo=baz&baz=abc&key=value',

  // the url parsed with url.parse()
  // compatible with url.format
  uriObj: {
    protocol: 'http:',
    slashes: true,
    auth: null,
    host: 'mockbin.com',
    port: null,
    hostname: 'mockbin.com',
    hash: null,
    search: 'key=value&baz=abc&foo=bar&foo=baz',
    query: { key: 'value', baz: 'abc', foo: [Object] },
    pathname: '/har',
    path: '/har?key=value&baz=abc&foo=bar&foo=baz',
    href: 'http://mockbin.com/har'
  },

  httpVersion: 'HTTP/1.1',

  // added to pass har-validator
  bodySize: 0,

  // added to pass har-validator
  headersSize: 0,

  queryString: [
    { name: 'foo', value: 'bar' },
    { name: 'foo', value: 'baz' },
    { name: 'baz', value: 'abc' }
  ],

  // "normalized" version of `queryString`
  // adds any additional query string values from the url
  // compatible with "querystring" node module
  queryObj: {
    key: 'value',
    baz: 'abc',
    foo: [ 'bar', 'baz' ]
  },

  headers: [
    { name: 'Accept', value: 'application/json' },
    { name: 'Content-Type', value: 'application/x-www-form-urlencoded' }
  ],

  // normalized headers array into a key => value object pair
  // header names are lowercased
  headersObj: {
    'accept': 'application/json',
    'content-type': 'application/x-www-form-urlencoded'
  },

  // same as headersObj but with Cookies added (if any exist in cookies array)
  allHeaders: {
    'accept': 'application/json',
    'content-type': 'application/x-www-form-urlencoded',
    'cookie': 'foo=bar; bar=baz'
  },

  cookies:  [
    { name: 'foo', value: 'bar' },
    { name: 'bar', value: 'baz' }
  ],

  // see below for different scenarios
  postData: [Object]
}

application/x-www-form-urlencoded

postData: {
  // added to pass har-validator
  size: 0,

  // original value
  mimeType: 'application/x-www-form-urlencoded',

  // original value
  params: [
    { name: 'foo', value: 'bar' },
    { name: 'foo', value: 'baz' },
    { name: 'baz', value: 'abc' }
  ],

  // "normalized" version of `params`
  // compatible with "querystring" node module
  paramsObj: {
    key: 'value',
    baz: 'abc',
    foo: [ 'bar', 'baz' ]
  }

  // the raw body in plain text
  // this value will be always overwritten in this scenario
  text: 'baz=abc&foo=bar&foo=baz'

  // see below
  jsonObj: false
}

application/json

• will match when postData.mimeType is one of: application/json, text/json, text/x-json, application/x-json
• In case of failure to parse postData.text as a JSON object, postData.mimeType is set to text/plain, postData.jsonObj remains as false. this is done so that the implementing target, would still attempt to post the raw body as is.
• This also emphasizes not to rely on postData.mimeType for the Content-Type header!

postData: {
  // added to pass har-validator
  size: 0,

  // original value
  mimeType: 'application/json',

  // ignored
  params: [],

  // default value
  paramsObj: false

  // the raw body in plain text
  text: '"{\"foo\": \"bar\"}"'

  // the parsed value of postData.text
  jsonObj: {
    foo: 'bar'
  }
}

multipart/form-data

• will match when postData.mimeType is one of: multipart/mixed multipart/related, multipart/form-data, multipart/alternative
• will force postData.mimeType to multipart/form-data
• will create/overwrite the Content-Type header if it does not exist, with the appropriate boundary flag.
• when no params[].value is present, will default to empty content

postData: {
  // added to pass har-validator
  size: 0,

  // original value
  mimeType: 'multipart/form-data',

  // parsed into text values
  params: [
    {
      name: 'foo',
      value: 'bar'
    }
  ]

  // ignored
  paramsObj: false

  // the raw body in plain text
  // generated based on appropriately parsing the `params` into a multi-boundary content string
  // this value will be always overwritten in this scenario
  text: '----------------------------591447866569479977899212\r\nContent-Disposition: form-data; name=\"foo\"\r\n\r\nbar\r\n----------------------------591447866569479977899212--'

  // ignored
  jsonObj: false
}

multipart/form-data (File Uploads)

postData: {
  // added to pass har-validator
  size: 0,

  // original value
  mimeType: 'multipart/form-data',

  // parsed into text values
  params: [
    {
      name: 'foo',
      value: 'Hello World',
      fileName: 'test/fixtures/files/hello.txt',
      contentType: 'text/plain'
    }
  ]

  // ignored
  paramsObj: false

  // the raw body in plain text
  // generated based on appropriately parsing the `params` into a multi-boundary content string
  // this value will be always overwritten in this scenario
  text: '----------------------------771333709043252625002993\r\nContent-Disposition: form-data; name=\"foo\"; filename=\"hello.txt\"\r\nContent-Type: text/plain\r\n\r\nHello World\r\n----------------------------771333709043252625002993--'

  // ignored
  jsonObj: false
}