HTTP client library with support for pluggable filters, including Zipkin, ASAP, etc
Features:
* Promise based API and internals.
* Builder interface allowing partial configuration and reuse.
* Convenient defaults for working with JSON requests and responses.
* Safe use of streams with robust error handling.
* Flexibility to stream or buffer any type of requests, responses or both.
* Supports chainable filters which can asynchronously modify requests and/or responses.
Existing filters:
* httplease-asap -- ASAP S2S Authentication
* httplease-cache -- HTTP caching using the Cache-Control headers
* httplease-retry -- Automatic request retries with optional fallback to alternative servers
Filters that are coming soon!
* Zipkin tracing
Possible future filters:
* Redirects
* Cookie jar
Install the library:
``
npm install --save httplease
For more examples have a look at the test/integration directory.
`
const httplease = require('httplease');
// this can be saved and reused as many times as you want
const httpClient = httplease.builder()
.withBaseUrl('http://example.com/basePath')
.withExpectStatus([200, 204])
.withBufferJsonResponseHandler()
.withTimeout(10000)
.withAgentOptions({keepAlive: true});
// make a request
httpClient
.withPath('/post')
.withJsonBody({someValue: 'some value'})
.withHeaders({'Cookie': 'key=value'})
.withMethodPost()
.send()
.then((response) => {
console.log(response.statusCode);
console.log('get header', response.getHeader('Some-Header'));
console.log('all headers', response.headers);
console.log('JSON body parsing by default', response.body);
})
.catch((err) => {
if (err instanceof httplease.errors.UnexpectedHttpResponseCodeError) {
// the response status check failed
console.log(err.response.statusCode);
console.log(err.response.headers);
console.log(err.response.body);
}
// some unknown error
throw err;
});
`
You can mix/match the builder style with params in send()
`
httplease.builder()
.withBufferJsonResponseHandler()
.withExpectStatus([200])
.send({
baseUrl: 'http://example.com/resource',
method: 'POST',
headers: {'Cookie': 'key=value'}
})
.then((response) => {
console.log('response complete');
});
`
httplease.builder()
.withMethodPost()
.withPath('http://example.com/upload-file')
.withHeaders({'Content-Type': 'application/json'})
.withStreamBody(fs.createReadStream('bigdata.json'))
.withDiscardBodyResponseHandler()
.withExpectStatus([200])
.send()
.then((response) => {
console.log('upload complete!');
});
`
httplease.builder()
.withMethodGet()
.withPath('http://example.com/')
.withExpectStatus([200])
.withTimeout(1000)
.withResponseHandler((response) => response.pipe(process.stdout))
.send()
.then((response) => {
console.log('download complete!');
});
`
npm install
`Run all checks
npm test
Perform a release
npm version 99.98.97
npm publish
git push
git push --tags
Pull requests, issues and comments welcome. For pull requests:
* Add tests for new features and bug fixes
* Follow the existing style
* Separate unrelated changes into multiple pull requests
See the existing issues for things to start contributing.
For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.
Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).
* CLA for corporate contributors
* CLA for individuals
Copyright (c) 2016 Atlassian and others.
Apache 2.0 licensed, see LICENSE file.