Module ringo/httpclient

A scalable HTTP client that provides both synchronous and asynchronous modes of operation.

Functions

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

Class Exchange

Instance Methods

Exchange ()

An Exchange encapsulates the Request and Response of an HTTP Exchange.

Exchange.prototype.content

The response body as String

Exchange.prototype.contentBytes

The response body as ByteString

Exchange.prototype.contentChunk

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.status

The response status code

Exchange.prototype.wait ()

Waits for the request to complete and returns the Exchange object itself. This method returns immediately if the request has already completed. Otherwise, it will block the current thread until completion.

Returns

the Exchange object

del (url, data, success, error)

Make a DELETE request. If a success callback is provided, the request is executed asynchronously and the function returns immediately. Otherwise, the function blocks until the request terminates.

Parameters

String url the url to request
Object|String data request data, optional
Function success callback in case of successful status code, optional
Function error callback in case of any error - transmission or response, optional

Returns

Exchange exchange object

See

request

get (url, data, success, error)

Make a GET request. If a success callback is provided, the request is executed asynchronously and the function returns immediately. Otherwise, the function blocks until the request terminates.

Parameters

String url the url to request
Object|String data request data, optional
Function success callback in case of successful status code, optional
Function error callback in case of any error - transmission or response, optional

Returns

Exchange exchange object

See

request

post (url, data, success, error)

Make a POST request. If a success callback is provided, the request is executed asynchronously and the function returns immediately. Otherwise, the function blocks until the request terminates.

Parameters

String url the url to request
Object|String|Binary|Stream data request data, optional
Function success callback in case of successful status code, optional
Function error callback in case of any error - transmission or response, optional

Returns

Exchange exchange object

See

request

put (url, data, success, error)

Make a PUT request. If a success callback is provided, the request is executed asynchronously and the function returns immediately. Otherwise, the function blocks until the request terminates.

Parameters

String url the url to request
Object|String|Binary|Stream data request data, optional
Function success callback in case of successful status code, optional
Function error callback in case of any error - transmission or response, optional

Returns

Exchange exchange object

See

request

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
  • contentType: the contentType
  • async: if true this method will return immedialtely , else it will block until the request is completed
  • binary: if true if content should be delivered as binary, else it will be decoded to string
  • promise: if true a promise that resolves to the request's Exchange object is returned instead of the Exchange object itself

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
  • part: called when a part of the response is available
  • 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