bhttp-api.yaml

- identifier: joepie91:bhttp
  license: WTFPL
  module: bhttp
  functions:
    - name: head
      returnValue: &RET_request
        type: Promise
        description: >
          Returns a Promise that resolves with the response object.
        lang:javascript:
          resolveValue:
            name: response
            type: Response
            description: >
              The HTTP response that was received.
      arguments:
        - &ARG_request_url
          name: url
          type: string
          description: >
            The URL to request, with protocol.
        - &ARG_request_options
          name: options
          type: object
          optional: true
          description: >
            Additional options to use for the request. Also allows for using the
            options offered by the standard HTTP/HTTPS modules.
          lang:javascript:
            inheritOptions: nodejs:https
            options:
              - name: stream
                type: boolean
                category: Basic options
                default: false
                description: >
                  Whether the response is meant to be streamed. If `true`, the
                  response body won't be parsed, an unread response stream is
                  returned, and the request is kept out of the 'agent' pool.
              - name: headers
                type: object
                category: Basic options
                description: >
                  Any extra request headers to set. (Non-custom) header names
                  must be lowercase.
              - name: followRedirects
                type: boolean
                category: Basic options
                default: true
                description: >
                  Whether to automatically follow redirects or not (the
                  redirect history is available as the redirectHistory
                  property on the response).
              - name: redirectLimit
                type: number
                category: Basic options
                default: 10
                description: >
                  The maximum amount of redirects to follow before erroring
                  out, to prevent redirect loops.

              - name: forceMultipart
                type: boolean
                category: Encoding and decoding
                default: false
                description: >
                  Ensures that `mulipart/form-data` encoding is used, no matter
                  what the payload contents are.
              - name: encodeJSON
                type: boolean
                category: Encoding and decoding
                default: false
                description: >
                  When set to `true`, the request payload will be encoded as
                  JSON. This cannot be used if you are using any streams in your
                  payload.
              - name: decodeJSON
                type: boolean
                category: Encoding and decoding
                default: false
                description: >
                  Defaults to false. When set to `true`, the response will
                  always be decoded as JSON, no matter what the `Content-Type`
                  says.

                  You'll probably want to keep this set to `false` - most APIs
                  send the correct `Content-Type` headers, and in those cases
                  `bhttp` will automatically decode the response as JSON.
              - name: noDecode
                type: boolean
                category: Encoding and decoding
                default: false
                description: >
                  Never decode the response, even if the `Content-Type` says
                  that it's JSON.

              - name: method
                type: string
                category: Advanced options
                description: >
                  The request method to use. You don't need this when using the
                  shorthand methods.
              - name: cookieJar
                type: CookieJar
                category: Advanced options
                description: >
                  A custom cookie jar to use. You'll probably want to use
                  `bhttp.session()` instead.
              - name: responseTimeout
                type: number
                category: Advanced options
                description: >
                  The timeout, in milliseconds, after which the request should
                  be considered to have failed if no response is received yet.
                  Note that this measures from the start of the request to the
                  start of the response, and is not a connection timeout.

                  If a timeout occurs, a `ResponseTimeoutError` will be thrown
                  asynchronously.
              - name: allowChunkedMultipart
                type: boolean
                category: Advanced options
                default: false
                description: >
                  Many servers don't support `multipart/form-data` when it is
                  transmitted with chunked transfer encoding (eg. when the
                  stream length is unknown), and silently fail with an empty
                  request payload - this is why `bhttp` disallows it by
                  default.

                  If you are *absolutely certain* that the endpoint supports
                  this functionality, you can override the behaviour by
                  setting this to `true`.
              - name: discardResponse
                type: boolean
                category: Advanced options
                default: false
                description: >
                  Whether to throw away the response without reading it. Only
                  really useful for fire-and-forget calls. This is almost
                  never what you want.
              - name: keepRedirectResponses
                type: boolean
                category: Advanced options
                default: false
                description: >
                  Whether to keep the response streams of redirects. You
                  probably don't need this.

                  __When enabling this, you must *explicitly* read out every
                  single redirect response, or you will experience memory
                  leaks!__
              - name: justPrepare
                type: boolean
                category: Advanced options
                default: false
                description: >
                  When set to `true`, bhttp just prepares the request, and
                  doesn't actually carry it out; useful if you want to make
                  some manual modifications.

                  Instead of a response, the method will asynchronously return
                  an array with the signature `[request, response,
                  requestState]` that you will need to pass into the
                  `bhttp.makeRequest()` method.

              - name: onUploadProgress
                type: function
                category: Event handlers
                description: >
                  A callback to call for upload progress events (this covers
                  both input streams and form data).
                callbackArguments:
                  - name: completedBytes
                    type: number
                    description: >
                      The amount of bytes that has been successfully
                      uploaded so far.
                  - name: totalBytes
                    type: number
                    description: >
                      The total amount of bytes to upload, ie. the request
                      payload size. If the request payload size is unknown,
                      this will be set to `undefined`.
                  - name: request
                    type: Request
                    description: >
                      The request object that the progress event applies to.
                      This is useful when dealing with automatic redirect
                      following, where multiple requests may occur.
              - name: onDownloadProgress
                type: function
                category: Event handlers
                description: >
                  A callback to call for download progress events. Note that
                  using the `progress` event on a response object is usually
                  a more practical option!
                callbackArguments:
                  - name: completedBytes
                    type: number
                    description: >
                      The amount of bytes that has been successfully
                      uploaded so far.
                  - name: totalBytes
                    type: number
                    description: >
                      The total amount of bytes to upload, ie. the request
                      payload size. If the request payload size is unknown,
                      this will be set to `undefined`.
                  - name: response
                    type: Response
                    description: >
                      The response object that the progress event applies to.
                      This is useful when dealing with automatic redirect
                      following, where multiple requests may occur.
        - &ARG_request_callback
          name: callback
          type: function
          optional: true
          description: >
            When using the nodeback API, the callback to use. If not specified,
            a Promise will be returned.
          lang:javascript:
            nodeback: true
            nodeified: true
            callbackArguments:
              - name: error
                type: Error
                description: >
                  Contains an Error object of some sort if an error occurred, or
                  `null` if the call was successful.
              - name: response
                type: Response
                optional: true
                description: >
                  Contains the HTTP response.
    - name: get
      arguments:
        - *ARG_request_url
        - *ARG_request_options
        - *ARG_request_callback
    - name: delete
      arguments:
        - *ARG_request_url
        - *ARG_request_options
        - *ARG_request_callback
    - name: post
      arguments:
        - *ARG_request_url
        - &ARG_request_data
          name: data
          type: [string, Buffer, Stream, object]
          description: >


        - *ARG_request_options
        - *ARG_request_callback