Bixby Developer Center

Provides helper methods for HTTP requests. For an example of how to use this API, see the HTTP API Calls sample capsule.

• Importing with JavaScript Runtime Version 1:

  var http = require('http')

• Importing with JavaScript Runtime Version 2:

  import http from 'http'

The following sections describe the available methods within this module. Each section includes a table that lists the parameters for that method, as well as the parameter's type and description.

HTTP Options

The following HTTP methods all take an options argument:

• getUrl()
• postUrl()
• deleteUrl()
• putUrl()
• oauthGetUrl()
• oauthPostUrl()
• oauthDeleteUrl()
• oauthPutUrl()

The options argument is a JSON object that can contain the following parameters:

• format: This specifies how the response will be parsed.

  • text: returns the raw response text, with no parsing.
  • json: expects the response to be JSON. Returns a JavaScript object.
  • xmljs: expects the response to be XML. The XML is converted to JSON, and then returned as a JavaScript object.
  • csv: expects the response to be a comma-separated value list. This will return an array of string values, or null if the CSV is not well-formed.
  • url: expects the response to be URL-encoded key/value pairs. Decodes the response and returns a JavaScript object.

• query: An object with attribute/value pairs to pass as arguments to the REST service.

• basicAuth: HTTP Basic Authentication. The value must be an object with "username" and "password".

• cacheTime: Cache time in milliseconds. All requests are cached in memory for cacheTime, which defaults to 3600000 (1 hour). An alternate cache time for a specific request can be provided. Set cacheTime to 0 to disable caching for requests. This can be particularly useful for POST requests.

• headers: An object with key/value pairs for additional HTTP headers. This can be used for custom Content-Type settings (such as XML).

• passAsJson (POST call only): If set to true, passes the request parameters in the body in JSON format and sets the content type appropriately.

• returnHeaders: If set to true, returns HTTP headers and status code. This also suppresses exceptions on HTTP error status codes, leaving this to the developer to handle.

• timeoutMs: Specify a timeout value in milliseconds. Valid values are 1 to 30000; if this option is not set, the default is 30000 ms. If the HTTP query times out, the web response will return a -1 HTTP status code. If your capsule needs to perform special handling when a timeout occurs, you must set the returnHeaders option to true to return the HTTP status code.

• skipResponse (only available with JavaScript Runtime Version 2): If set to true, the HTTP call will not wait for an actual response to be returned from the server. This is most suitable for bypassing the blocking effects of non-critical calls, such as logging and analytics. When this option is enabled, the method's return value will be the empty string, unless returnHeaders is set to true. In that case, this object will be returned as the response:

  {
    "status": 202,    // HTTP 202 Accepted
    "headers": {},
    "responseText": ""
  }

  Note

  If cacheTime is greater than 0 on a request with skipResponse: true, the 202 response will be cached. Consider setting cacheTime: 0 to avoid caching if you want the request to be made every call; otherwise, the default caching will result in the 202 response being cached.

  For each execution, you can fire at most 10 skipResponse requests. When the limit is exceeded, the skipResponse flag will be ignored.

Example

// Set options: the response is expected in JSON, and the query is a
// JSON object of { "searchTerm": "value of searchTerm variable" }

var options = {
  format: 'json',
  query: {
    searchTerm: searchTerm,
  },
}

// call endpoint defined in remote.url configuration, parse the JSON
// response, return resulting object

var response = http.getUrl(config.get('remote.url') + '/search', options)

{
  "status": 200,
  "headers": {
    "header1": "value"
  },
  "responseText": "text form of response",
  "parsed": {
    "key1": "value1",
    "key2": "value2"
  }
}

Setting HTTP Headers

You can set headers information in the options parameter, like in the following example:

let options = {
  format: 'json',
  headers: {
    accept: 'application/json',
  },
}

let response = http.getUrl('https://my-capsule.com/api/search/', options)

Cache Settings

Result caching is affected by either of the following:

• The cacheTime option in an HTTP request (see HTTP Options).
• The Cache-Control HTTP header in the HTTP response sent by the server.

Bixby supports the following Cache-Control settings:

• no-cache or no-store: The result will not be cached at all, regardless of the cacheTime setting.
• max-age=<seconds>: The result will be cached for a maximum of the specified time.

If both cacheTime and Cache-Control: max-age are specified for the same request, the result will be cached for the shorter of the two values.

HTTP parameters

Requests that take the params parameter can accept any type. When the Content-Type is set to JSON, the HTTP body sent as part of the request will be JSON. For other content types, the parameters will be sent as a string. Objects with key/value pairs will be appropriately URL-encoded (for example, key1=value1&key2=value2...) when stringified.

http.getUrl(url, options)

Perform an HTTP GET request. By default, the return value is a string (equivalent to setting the format option to text); this can be changed by using a different format option in the options argument.

Kind: Static method of http
Access: Public

For an example of using http.getUrl(), read Calling a Web Service from a Local Endpoint.

http.postUrl(url, params, options)

Perform an HTTP POST request.

Kind: Static method of http

Supports all the options from getUrl(), plus the following:

• passAsJson: If true, pass the request parameters in the body in JSON format.

http.deleteUrl(url, params, options)

Perform an HTTP DELETE request.

Kind: Static method of http

Supports all the options from getUrl(), plus the following:

• passAsJson: If true, pass the request parameters in the body in JSON format

http.putUrl(url, params, options)

Perform an HTTP PUT request.

Kind: Static method of http

Supports all the options from getUrl(), plus the following:

• passAsJson: If true, pass the request parameters in the body in JSON format

http.oauthGetUrl(url, options)

Perform an HTTP GET request, attached with the OAuth appropriate access keys. (See Implementing JavaScript Actions for details.)

Kind: Static method of http
Access: Public

Supports the same options as getUrl().

http.oauthPostUrl(url, params, options)

Perform an HTTP POST request, attached with the OAuth appropriate access keys. (See Implementing JavaScript Actions for details.)

Kind: Static method of http
Access: Public

Supports the same parameters and options as postUrl().

http.oauthDeleteUrl(url, params, options)

Perform an HTTP DELETE request, attached with the OAuth appropriate access keys. (See Implementing JavaScript Actions for details.)

Kind: Static method of http
Access: Public

Supports the same parameters and options as deleteUrl().

http.oauthPutUrl(url, params, options)

Perform an HTTP PUT request, attached with the OAuth appropriate access keys. (See Implementing JavaScript Actions for details.)

Kind: Static method of http
Access: Public

Supports the same parameters and options as putUrl().

http.makeQueryString(args)

Return a properly-formatted query string.

Kind: Static method of http
Access: Public

The object key-value pairs are used as the query parameter keys and values. Values will be URL-encoded. You can pass this object to http.makeQueryString():

{ "color": "red", "flavor": "peppermint stick" }

The queryString returned is:

color=red&flavor=peppermint%20stick