# HTTPSnippet > HTTP Request snippet generator for _many_ languages & tools including: `cURL`, `HTTPie`, `Javascript`, `Node`, `C`, `Java`, `PHP`, `Objective-C`, `Swift`, `Python`, `Ruby`, `Rust`, `C#`, `Go`, `OCaml` and [more](https://github.com/Kong/httpsnippet/wiki/Targets)! Relies on the popular [HAR](http://www.softwareishard.com/blog/har-12-spec/#request) format to import data and describe HTTP calls. See it in action on [ReadMe](https://docs.readme.com/reference/getopenroles). [![Build](https://github.com/readmeio/httpsnippet/workflows/CI/badge.svg)](https://github.com/readmeio/httpsnippet) ## Installation ```shell npm install --save @readme/httpsnippet ``` ## Usage ### HTTPSnippet(input [, options]) #### input _Required_ Type: `object` The [HAR](http://www.softwareishard.com/blog/har-12-spec/#request) request object to generate a snippet for. ```ts import { HTTPSnippet } from '@readme/httpsnippet'; const snippet = new HTTPSnippet({ method: 'GET', url: 'https://httpbin.org/anything', }); ``` #### options Type: `object` Available options: - `harIsAlreadyEncoded` (`boolean`): In the event of you supplying a `source` HAR that already contains escaped data (query and cookie parameters)strings, this allows you to disable automatic encoding of those parameters to prevent them from being double-escaped. ### convert(target [, options]) #### target _Required_ Type: `string` Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets) #### options Type: `object` Target options, _see [wiki](https://github.com/Kong/httpsnippet/wiki/Targets) for details_ ```ts import { HTTPSnippet } from '@readme/httpsnippet'; const snippet = new HTTPSnippet({ method: 'GET', url: 'https://httpbin.org/anything', }); // generate Node.js: Native output console.log(snippet.convert('node')); // generate Node.js: Native output, indent with tabs console.log( snippet.convert('node', { indent: '\t', }), ); ``` ### convert(target [, client, options]) #### Target _Required_ Type: `string` Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets) #### Client Type: `string` Name of conversion target [client library](https://github.com/Kong/httpsnippet/wiki/Targets) #### Options Type: `object` Target options, _see [wiki](https://github.com/Kong/httpsnippet/wiki/Targets) for details_ ```ts import { HTTPSnippet } from '@readme/httpsnippet'; const snippet = new HTTPSnippet({ method: 'GET', url: 'https://httpbin.org/anything', }); // generate Shell: cURL output console.log( snippet.convert('shell', 'curl', { indent: '\t', }), ); // generate Node.js: Axios output console.log(snippet.convert('node', 'axios')); ``` ### addTarget(target) #### target _Required_ Type: `object` Representation of a [conversion target](https://github.com/Kong/httpsnippet/wiki/Creating-Targets). Can use this to use targets that are not officially supported. ```ts import { customLanguageTarget } from 'httpsnippet-for-my-lang'; HTTPSnippet.addTarget(customLanguageTarget); ``` ### addTargetClient(target, client) #### Target _Required_ Type: `string` Name of [conversion target](https://github.com/Kong/httpsnippet/wiki/Targets) #### Client _Required_ Type: `object` Representation of a [conversion target client](https://github.com/Kong/httpsnippet/wiki/Creating-Targets). Can use this to use target clients that are not officially supported. ```ts import { customClient } from 'httpsnippet-for-my-node-http-client'; HTTPSnippet.addTargetClient('node', customClient); ``` ### addClientPlugin(plugin) #### Plugin _Required_ Type: `object` The client plugin to install. ```ts addClientPlugin({ target: 'node', client: { info: { key: 'custom', title: 'Custom HTTP library', link: 'https://example.com', description: 'A custom HTTP library', extname: '.custom', }, convert: () => { return 'This was generated from a custom client.'; }, }, }); ``` The above example will create a new `custom` client snippet generator for the `node` target. ## Documentation At the heart of this module is the [HAR Format](http://www.softwareishard.com/blog/har-12-spec/#request) as the HTTP request description format, please review some of the sample JSON HAR Request objects in [test fixtures](/test/fixtures/requests), or read the [HAR Docs](http://www.softwareishard.com/blog/har-12-spec/#request) for more details. For detailed information on each target, please review the [wiki](https://github.com/Kong/httpsnippet/wiki). ## Differences from `kong/httpsnippet` There are some major differences between this library and the [httpsnippet](https://github.com/Kong/httpsnippet) upstream: - Includes a full integration test suite for a handful of clients and targets. - Does not ship with a CLI component. - Does not do any HAR schema validation. It's just assumed that the HAR you're supplying to the library is already valid. - The main `HTTPSnippet` export contains an `options` argument for an `harIsAlreadyEncoded` option for disabling [escaping](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) of cookies and query strings in URLs. - We added this because all HARs that we interact with already have this data escaped and this option prevents them from being double encoded, thus corrupting the data. - Does not support the `insecureSkipVerify` option on `go:native`, `node:native`, `ruby:native`, and `shell:curl` as we don't want snippets generated for our users to bypass SSL certificate verification. - Includes a full plugin system, `#addClientPlugin`, for quick installation of a target client. - Node - `fetch` - Body payloads are treated as an object literal and wrapped within `JSON.stringify()`. We do this to keep those targets looking nicer with those kinds of payloads. This also applies to the JS `fetch` target as well. - `request` - Does not provide query string parameters in a `params` argument due to complexities with query encoding. - PHP - `guzzle` - Snippets have `require_once('vendor/autoload.php');` prefixed at the top. - Python - `python3` - Does not ship this client due to its incompatibility with being able to support file uploads. - `requests` - Does not provide query string parameters in a `params` argument due to complexities with query encoding. ## License [MIT](LICENSE) © [Kong](https://konghq.com) [license-url]: https://github.com/Kong/httpsnippet/blob/master/LICENSE [npm-url]: https://www.npmjs.com/package/@readme/httpsnippet [npm-license]: https://img.shields.io/npm/l/@readme/httpsnippet.svg?style=flat-square [npm-version]: https://img.shields.io/npm/v/@readme/httpsnippet.svg?style=flat-square