RingoJS

Module ringo/httpclient

A module for sending HTTP requests and receiving HTTP responses.

Example

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

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

Functions

Class BinaryPart

Class TextPart


BinaryPart (data, fileName, contentType)

Example

request({
  url: "http://example.org/post-multipart",
  method: "POST",
  contentType: "multipart/form-data",
  data: {
    "image": new BinaryPart(binaryStream, "image.png"),
    "document": new BinaryPart(binaryStream, "invoce.doc", "application/msword")
  }
});

Parameters

String data

the data

String fileName

(optional) file name

String contentType

(optional) content type of the file

Returns

BinaryPart

A newly constructed BinaryPart instance


Exchange (url, options)

Parameters

String url

The URL

Object options

The options

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

Example

request({
  url: "http://example.org/post-multipart",
  method: "POST",
  contentType: "multipart/form-data",
  data: {
    "simple": new TextPart("my string", "utf-8"),
    "text": new TextPart(textStream, "utf-8"),
    "txtFile": new TextPart(txtStream, "utf-8", "test.txt")
  }
});

Parameters

String|TextStream data

text data to write

String charset

the charset

String fileName

(optional) file name

Returns

TextPart

A newly constructed TextPart instance


del (url, data)

Executes a DELETE request.

Parameters

String url

The URL

Object|String data

The data to append as GET parameters to the URL

Returns

Exchange

The Exchange instance representing the request and response


get (url, data)

Executes a GET request.

Parameters

String url

The URL

Object|String data

The data to append as GET parameters to the URL

Returns

Exchange

The Exchange instance representing the request and response


post (url, data)

Executes a POST request.

Parameters

String url

The URL

Object|String|Stream|Binary data

The data to send to the server

Returns

Exchange

The Exchange instance representing the request and response


put (url, data)

Executes a PUT request.

Parameters

String url

The URL

Object|String|Stream|Binary data

The data send to the server

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 parameters as string or object for GET, DELETE, and similar methods. For POST or PUT requests, the body must be string, object, Stream, or Binary. For a multipart form POST requests, all parameter values must be instances of TextPart or BinaryPart.
  • headers: request headers
  • username: username for HTTP authentication
  • password: password for HTTP authentication
  • proxy: proxy-settings as string (http://proxy-hostname:port) or object {host: "proxy-hostname", port: 3128}
  • contentType: the contentType. If set to multipart/form-data, PUT and POST request's data will be treated as multipart form uploads.
  • 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)

Parameters

Object options

Returns

Exchange

exchange object