node-api-http.txt

*node-api-http.txt*      For Node.js module `HTTP` version v3.3.0.

Node.js Documentation
https://nodejs.org

==============================================================================
CONTENTS                                                   *node-api-contents*

  1. Intro                                                     |node-api-http|
  2. Methods                                           |node-api-http-methods|
    2.1. http.createServer([requestListener])   |node-api-http.createServer()|
    2.2. http.createClient([port][, host])      |node-api-http.createClient()|
    2.3. http.request(options[, callback])           |node-api-http.request()|
    2.4. http.get(options[, callback])                   |node-api-http.get()|
  3. Properties                                     |node-api-http-properties|
    3.1. `METHODS` {Array}                             |node-api-http.METHODS|
    3.2. `STATUS_CODES` {Object}                  |node-api-http.STATUS_CODES|
    3.3. http.globalAgent                          |node-api-http.globalAgent|
    3.4. http.IncomingMessage                  |node-api-http.IncomingMessage|

==============================================================================
INTRO                                                          *node-api-http*

Stability: 2 - Stable

To use the HTTP server and client one must `require('http')`.

The HTTP interfaces in io.js are designed to support many features
of the protocol which have been traditionally difficult to use.
In particular, large, possibly chunk-encoded, messages. The interface is
careful to never buffer entire requests or responses--the
user is able to stream data.

HTTP message headers are represented by an object like this:

 >
  { 'content-length': '123',
    'content-type': 'text/plain',
    'connection': 'keep-alive',
    'host': 'mysite.com',
    'accept': '*/*' }
<

Keys are lowercased. Values are not modified.

In order to support the full spectrum of possible HTTP applications, io.js's
HTTP API is very low-level. It deals with stream handling and message
parsing only. It parses a message into headers and body but it does not
parse the actual headers or the body.

Defined headers that allow multiple values are concatenated with a `,`
character, except for the `set-cookie` and `cookie` headers which are
represented as an array of values.  Headers such as `content-length`
which can only have a single value are parsed accordingly, and only a
single value is represented on the parsed object.

The raw headers as they were received are retained in the `rawHeaders`
property, which is an array of `[key, value, key2, value2, ...]`.  For
example, the previous message header object might have a `rawHeaders`
list like the following:

 >
  [ 'ConTent-Length', '123456',
    'content-LENGTH', '123',
    'content-type', 'text/plain',
    'CONNECTION', 'keep-alive',
    'Host', 'mysite.com',
    'accepT', '*/*' ]
<

==============================================================================
METHODS                                                *node-api-http-methods*

------------------------------------------------------------------------------
http.createServer([requestListener])            *node-api-http.createServer()*

Returns a new instance of *node-api-http_class_http_server*.

The `requestListener` is a function which is automatically
added to the `'request'` event.


------------------------------------------------------------------------------
http.createClient([port][, host])               *node-api-http.createClient()*

Constructs a new HTTP client. `port` and `host` refer to the server to be
connected to.


------------------------------------------------------------------------------
http.request(options[, callback])                    *node-api-http.request()*

io.js maintains several connections per server to make HTTP requests.
This function allows one to transparently issue requests.

`options` can be an object or a string. If `options` is a string, it is
automatically parsed with [url.parse()][].

Options:

* `protocol`: Protocol to use. Defaults to `'http'`.

  * `host`: A domain name or IP address of the server to issue the request to.
    Defaults to `'localhost'`.
    * `hostname`: Alias for `host`. To support `url.parse()` `hostname` is
      preferred over `host`.
    * `family`: IP address family to use when resolving `host` and `hostname`.
      Valid values are `4` or `6`. When unspecified, both IP v4 and v6 will be
      used.
    * `port`: Port of remote server. Defaults to 80.
    * `localAddress`: Local interface to bind for network connections.
    * `socketPath`: Unix Domain Socket (use one of host:port or socketPath).
    * `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
    * `path`: Request path. Defaults to `'/'`. Should include query string if any.
      E.G. `'/index.html?page=12'`. An exception is thrown when the request path
      contains illegal characters. Currently, only spaces are rejected but that
      may change in the future.
    * `headers`: An object containing request headers.
    * `auth`: Basic authentication i.e. `'user:password'` to compute an
      Authorization header.
    * `agent`: Controls [Agent][] behavior. When an Agent is used request will
      default to `Connection: keep-alive`. Possible values:
      * `undefined` (default): use [globalAgent][] for this host and port.
    * `Agent` object: explicitly use the passed in `Agent`.
    * `false`: opts out of connection pooling with an Agent, defaults request to
      `Connection: close`.

  The optional `callback` parameter will be added as a one time listener for
  the ['response'][] event.


  `http.request()` returns an instance of the [http.ClientRequest][]
  class. The `ClientRequest` instance is a writable stream. If one needs to
  upload a file with a POST request, then write to the `ClientRequest` object.


  Example:


   >
    var postData = querystring.stringify({
      'msg' : 'Hello World!'
    });

    var options = {
      hostname: 'www.google.com',
      port: 80,
      path: '/upload',
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': postData.length
      }
    };

    var req = http.request(options, function(res) {
      console.log('STATUS: ' + res.statusCode);
      console.log('HEADERS: ' + JSON.stringify(res.headers));
      res.setEncoding('utf8');
      res.on('data', function (chunk) {
        console.log('BODY: ' + chunk);
      });
      res.on('end', function() {
        console.log('No more data in response.')
      })
    });

    req.on('error', function(e) {
      console.log('problem with request: ' + e.message);
    });

    // write data to request body
    req.write(postData);
    req.end();
<

  Note that in the example `req.end()` was called. With `http.request()` one
  must always call `req.end()` to signify that you're done with the request -
  even if there is no data being written to the request body.


  If any error is encountered during the request (be that with DNS resolution,
  TCP level errors, or actual HTTP parse errors) an `'error'` event is emitted
  on the returned request object.


  There are a few special headers that should be noted.



  * Sending a 'Connection: keep-alive' will notify io.js that the connection to
  the server should be persisted until the next request.

* Sending a 'Content-length' header will disable the default chunked encoding.

* Sending an 'Expect' header will immediately send the request headers.
  Usually, when sending 'Expect: 100-continue', you should both set a timeout
  and listen for the `continue` event. See RFC2616 Section 8.2.3 for more
  information.

* Sending an Authorization header will override using the `auth` option
  to compute basic authentication.



------------------------------------------------------------------------------
http.get(options[, callback])                            *node-api-http.get()*

Since most requests are GET requests without bodies, io.js provides this
convenience method. The only difference between this method and `http.request()`
is that it sets the method to GET and calls `req.end()` automatically.

Example:

 >
  http.get("http://www.google.com/index.html", function(res) {
    console.log("Got response: " + res.statusCode);
  }).on('error', function(e) {
    console.log("Got error: " + e.message);
  });
<



==============================================================================
PROPERTIES                                          *node-api-http-properties*

------------------------------------------------------------------------------
`METHODS` {Array}                                      *node-api-http.METHODS*

A list of the HTTP methods that are supported by the parser.


------------------------------------------------------------------------------
`STATUS_CODES` {Object}                           *node-api-http.STATUS_CODES*

A collection of all the standard HTTP response status codes, and the
short description of each.  For example, `http.STATUS_CODES[404] === 'Not
Found'`.


------------------------------------------------------------------------------
http.globalAgent                                   *node-api-http.globalAgent*

Global instance of Agent which is used as the default for all http client
requests.


------------------------------------------------------------------------------
http.IncomingMessage                           *node-api-http.IncomingMessage*

An `IncomingMessage` object is created by [http.Server][] or
[http.ClientRequest][] and passed as the first argument to the `'request'`
and `'response'` event respectively. It may be used to access response status,
headers and data.

It implements the [Readable Stream][] interface, as well as the
following additional events, methods, and properties.



 vim:tw=78:ts=8:ft=help