RingoJS

Module ringo/httpclient

A module for sending HTTP requests and receiving HTTP responses.

Example

var {request} = require('ringo/httpclient');
var exchange = request({
   method: 'GET',
   url: 'http://ringojs.org/',
   headers: {
      'x-custom-header': 'foobar'
   }
});

if(exchange.status == 200) {
   console.log(exchange.content);
}

Functions

  • del(url, data, success, error)
  • get(url, data, success, error)
  • post(url, data, success, error)
  • put(url, data, success, error)
  • request(options)

Class BinaryPart

Class TextPart


BinaryPart (data, charset, filename)

Parameters

String data

The data

String charset

The charset

String filename

An optional file name

Returns

BinaryPart

A newly constructed BinaryPart instance


Exchange (url, options, callbacks)

Parameters

String url

The URL

Object options

The options

Object callbacks

An object containing success, error and complete callback methods

Returns

Exchange

A newly constructed Exchange instance


Exchange.prototype. connection

The connection used by this Exchange instance.


Exchange.prototype. content

The response body as String.


Exchange.prototype. contentBytes

The response body as ByteArray.


Exchange.prototype. contentLength

The response content length.


Exchange.prototype. contentType

The response content type.


Exchange.prototype. cookies

The cookies set by the server.


Exchange.prototype. done

True if the request has completed, false otherwise.


Exchange.prototype. encoding

The response encoding.


Exchange.prototype. headers

The response headers.


Exchange.prototype. message

The response status message.


Exchange.prototype. status

The response status code.


Exchange.prototype. url

The URL wrapped by this Exchange instance.


TextPart (data, charset, filename)

Parameters

String|TextStream data

The data

String charset

The charset

String filename

An optional file name

Returns

TextPart

A newly constructed TextPart instance


del (url, data, success, error)

Executes a DELETE request.

Parameters

String url

The URL

Object|String data

The data to append as GET parameters to the URL

Function success

Optional success callback

Function error

Optional error callback

Returns

Exchange

The Exchange instance representing the request and response


get (url, data, success, error)

Executes a GET request.

Parameters

String url

The URL

Object|String data

The data to append as GET parameters to the URL

Function success

Optional success callback

Function error

Optional error callback

Returns

Exchange

The Exchange instance representing the request and response


post (url, data, success, error)

Executes a POST request.

Parameters

String url

The URL

Object|String|Stream|Binary data

The data to send to the server

Function success

Optional success callback

Function error

Optional error callback

Returns

Exchange

The Exchange instance representing the request and response


put (url, data, success, error)

Executes a PUT request.

Parameters

String url

The URL

Object|String|Stream|Binary data

The data send to the server

Function success

Optional success callback

Function error

Optional error callback

Returns

Exchange

The Exchange instance representing the request and response


request (options)

Make a generic request.

Generic request options

The options object may contain the following properties:

  • url: the request URL
  • method: request method such as GET or POST
  • data: request data as string, object, or, for POST or PUT requests, Stream or Binary.
  • headers: request headers
  • username: username for HTTP authentication
  • password: password for HTTP authentication
  • proxy: proxy-settings as string ("proxy.host:port") or object {host: "hostname.org", port: 3128}
  • contentType: the contentType
  • binary: if true if content should be delivered as binary, else it will be decoded to string
  • followRedirects: whether HTTP redirects (response code 3xx) should be automatically followed; default: true
  • readTimeout: setting for read timeout in millis. 0 return implies that the option is disabled (i.e., timeout of infinity); default: 30000 ms (or until impl decides its time)
  • connectTimeout: Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced by this URLConnection. A timeout of zero is interpreted as an infinite timeout.; default: 60000 ms (or until impl decides its time)

Callbacks

The options object may also contain the following callback functions:

  • complete: called when the request is completed
  • success: called when the request is completed successfully
  • error: called when the request is completed with an error
  • beforeSend: called with the Exchange object as argument before the request is sent

The following arguments are passed to the complete, success and part callbacks:

  1. content: the content as String or ByteString
  2. status: the HTTP status code
  3. contentType: the content type
  4. exchange: the exchange object

The following arguments are passed to the error callback:

  1. message: the error message. This is either the message from an exception thrown during request processing or an HTTP error message
  2. status: the HTTP status code. This is 0 if no response was received
  3. exchange: the exchange object

Parameters

Object options

Returns

Exchange

exchange object