Skip to content

Latest commit

 

History

History
81 lines (60 loc) · 4.2 KB

API.md

File metadata and controls

81 lines (60 loc) · 4.2 KB
Raw

API

gimme

gimme : { k: v } -> Promise Boom Response

Accepts an object of request params, described below.

Returns a Promise that either resolves with a Response, or rejects with an appropriate Boom error for the status code of the response & a cry property to assist with error reporting.

The following params are accepted:

Name Type Default Description
agent Agent optional shared agent to manage connection persistence
body Any data to serialize and send as the request body
deserialize Function JSON.stringify function with which to deserialize the response body
headers Object {} headers to include on the request
json Boolean true if true, assumes json-formatted request and response
jwt String json web token to include in the Authorization header
method String GET must be a valid http request method
query Object data to serialize and append to the url as a query string
serialize Function JSON.parse function with which to serialize the request body
stream Boolean false if true, the response body will be a stream.Readable
timeout Number 0 (never) milliseconds before the request times out
url String required: the url of the request

Response object

The resolved Response object of a successful request is a POJO with the following properties:

Property Type Details
body Any deserialized response body (see details below)
headers Object map of headers, with downcased header names as keys
statusCode Number three-digit response status code
statusMessage String response status message (reason phrase)

If json: true, the body can be any JSON serializable type. If stream: true, the body will be a stream.Readable. Otherwise, the body will be a String.

JSON by default

The json: true flag is set by default, which has the following effects on the request:

  • deserialize defaults to JSON.stringify
  • serialize defaults to JSON.parse
  • The content-type header is forced to application/json

Setting json: false prevents the effects listed above if desired.

Streaming the response

Setting stream: true will return a Response with stream.Readable body. You may then pipe the body anywhere you like, or pass it as the body of a paperplane response, or the Body of an AWS upload request.

const aws   = require('aws-sdk')
const gimme = require('@articulate/gimme')
const { promisify } = require('@articulate/funky')

const s3     = new aws.S3()
const upload = promisify(s3.upload, s3)

const uploadToS3 = res =>
  upload({
    ACL: 'public-read',
    Body: res.body,
    Bucket: 'my-bucket',
    ContentType: res.headers['content-type'],
    Key: '200-response'
  })

gimme({ json: false, stream: true, url: 'http://httpstat.us/200' })
  .then(uploadToS3)