Plug-in Proxy Request

Plug-in Proxy Request - kintone.plugin.app.proxy()

Runs an external REST API from a plug-in.
If your external REST API requires sensitive information such as secret keys, use the Set Config for proxy() API and Get Config for proxy() API mentioned later on, to save and get these data for the external REST API.

Function

kintone.plugin.app.proxy(pluginId, url, method, headers, data, successCallback, failureCallback)

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
pluginId Object Yes The plug-in ID of the plug-in that will run the API.
url String Yes The URL of the REST API that you will run.
method String Yes The HTTP method. Specify one of the following: GET / POST / PUT / DELETE.
headers Object Yes The request header.
The parameters specified here will be sent with the parameters that were saved in the plug-in by the kintone.plugin.app.setProxyConfig() function.
data Object/String Yes The request data. To ignore this parameter, input {}.
The data specified here will be sent with the data that was saved in the plug-in by the kintone.plugin.app.setProxyConfig() function.
Applied only for POST/PUT requests. Ignored for GET/DELETE requests.
For GET/DELETE requests, set the parameter on the QueryString of the URL instead.
successCallback Function Optional The function that will run after the request has finished. The following three data will be passed as the parameters:
  • First parameter: Response body (String)
  • Second parameter: Status code (number)
  • Third parameter: Response header (Object)
If ignored, a kintone.Promise object will be returned that can be fulfilled with an array containing the Response body (string), Status code (number) and Response header (Object) mentioned above.
failureCallback Function Optional The function that will run when the request fails. The response body will be passed to the function parameter as a string.
If the callback is ignored, a kintone.Promise object will be returned that can be fulfilled with the Response body (string) from the Kintone plug-in proxy API.

Response

A kintone.Promise object will be returned if the successCallback or failureCallback parameters are ignored. Otherwise, there will be no response.

Available Pages

This method can be used in the following pages:

Desktop pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Graph
  • Print

Mobile pages:

  • Record List
  • Record Details
  • Record Create
  • Record Edit
  • Graph

Sample Request

1
2
3
4
5
kintone.plugin.app.proxy('ghjdjfpgeoghqsmczgajibgpxoffmgaa', 'https://api.example.com', 'GET', {}, {}, function(body, status, headers) {
  console.log(status, JSON.parse(body), headers);
}, function(error) {
  console.log(error); // Display the response body (string) from the proxy API
});

Sample Request using Promises

1
2
3
4
5
6
7
8
9
kintone.plugin.app.proxy('ghjdjfpgeoghqsmczgajibgpxoffmgaa', 'https://api.example.com', 'GET', {}, {}).then(function(args) {
  /*  args[0] -> body(String)
     *  args[1] -> status(Number)
     *  args[2] -> headers(Object)
     */
  console.log(args[1], JSON.parse(args[0]), args[2]);
}, function(error) {
  console.log(error); // Display the response body (string) from the proxy API
});

Notes

  • If the request origin domain has IP restrictions and attempts to access another App in the same domain, the kintone.com IP Addresses (External link) can be allowed to grant access to the plug-in.
  • Please note that this allows any kintone.com domain to access the API, and therefore is not recommended from a security standpoint.
  • When using Kintone REST API on your own Kintone domain, use the Kintone REST API Request instead of the kintone.proxy() API.

Limitations

  • Specifying a non-existent url will return an error status code of 503 (DNS Cache Missing).
  • This API can only handle a response body of characters. Images, or other binary data are not supported.
  • The Content-Length header and Transfer-Encoding headers are automatically added if the HTTP Method is set to POST or PUT.
  • Explicitly setting headers will cause an error.