@readme/httpsnippet
v11.0.0
Published
HTTP Request snippet generator for *most* languages
Downloads
11,769
Readme
HTTP Snippet
HTTP Request snippet generator for many languages & tools including:
cURL
,HTTPie
,Javascript
,Node
,C
,Java
,PHP
,Objective-C
,Swift
,Python
,Ruby
,C#
,Go
,OCaml
and more!
Relies on the popular HAR format to import data and describe HTTP calls.
See it in action on ReadMe.
Installation
npm install --save @readme/httpsnippet
Usage
HTTPSnippet(input [, options])
input
Required Type: object
The HAR request object to generate a snippet for.
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 asource
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
options
Type: object
Target options, see wiki for details
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
Client
Type: string
Name of conversion target client library
Options
Type: object
Target options, see wiki for details
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. Can use this to use targets that are not officially supported.
import { customLanguageTarget } from 'httpsnippet-for-my-lang';
HTTPSnippet.addTarget(customLanguageTarget);
addTargetClient(target, client)
Target
Required Type: string
Name of conversion target
Client
Required Type: object
Representation of a conversion target client. Can use this to use target clients that are not officially supported.
import { customClient } from 'httpsnippet-for-my-node-http-client';
HTTPSnippet.addTargetClient('node', customClient);
addClientPlugin(plugin)
Plugin
Required Type: object
The client plugin to install.
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 as the HTTP request description format, please review some of the sample JSON HAR Request objects in test fixtures, or read the HAR Docs for more details.
For detailed information on each target, please review the wiki.
Differences from kong/httpsnippet
There are some major differences between this library and the 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 anoptions
argument for anharIsAlreadyEncoded
option for disabling escaping 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 ongo:native
,node:native
,ruby:native
, andshell: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 JSfetch
target as well.
- Body payloads are treated as an object literal and wrapped within
request
- Does not provide query string parameters in a
params
argument due to complexities with query encoding.
- Does not provide query string parameters in a
- PHP
guzzle
- Snippets have
require_once('vendor/autoload.php');
prefixed at the top.
- Snippets have
- 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.
- Does not provide query string parameters in a