kintone-rest-api-client
API client for Kintone REST API.
It supports both browser environment (Kintone customization & plugin) and Node.js environment.
Installation
1. Install with npm
This library is distributed on npm
.
npm install @kintone/rest-api-client
You can then use require
or import
to import the library.
const { KintoneRestAPIClient } = require("@kintone/rest-api-client");
import { KintoneRestAPIClient } from "@kintone/rest-api-client";
2. UMD files (for browser environment)
This library also provides two Universal Module Definition (UMD) files:
After loading this, you can use KintoneRestAPIClient
directly.
In Kintone customization, please add this URL in "JavaScript and CSS Customization" setting of your app.
NOTE: The UMD links are using the latest
tag to point to the latest version of the library. This pointer is unstable, it shifts as we release new versions. You should consider pointing to a specific version, such as 1.0.0
.
Browsers support
Edge | Firefox | Chrome | Safari |
---|
Latest version | Latest version | Latest version | Latest version |
Usage
Here is a sample code that retrieves records of an app.
const client = new KintoneRestAPIClient({
baseUrl: "https://example.cybozu.com",
auth: {
username: process.env.KINTONE_USERNAME,
password: process.env.KINTONE_PASSWORD,
},
});
client.record
.getRecords({ app: "1" })
.then((resp) => {
console.log(resp.records);
})
.catch((err) => {
console.log(err);
});
Global
Name | Type | Description |
---|
version | String | Provides the used version of KintoneRestAPIClient. |
Parameters for KintoneRestAPIClient
Name | Type | Required | Description |
---|
baseUrl | String | Conditionally Required | The base URL for your Kintone environment. It must start with https . (e.g. https://example.kintone.com) Required in Node.js environment. If you omit it in browser environment, location.origin will be used. The protocol of baseUrl must be https except when hostname is localhost . |
auth | Object | Conditionally Required | The object for authentication. See Authentication. |
guestSpaceId | Number or String | | The guest space ID. If you are dealing with apps that are in guest spaces, please specify this. |
basicAuth | Object | | If your Kintone environment uses Basic authentication, please specify its username and password. |
basicAuth.username | String | | The username of Basic authentication. |
basicAuth.password | String | | The password of Basic authentication. |
httpsAgent | Object | | This parameter is available only in Node.js environment. The custom HTTPS agent to be used when request. The agent should be compatible with https.Agent. |
clientCertAuth | Object | | This parameter is available only in Node.js environment. When httpsAgent parameter is given, this parameter is unavailable. If your Kintone environment uses Client Certificate authentication, please specify the certificate file and password. |
clientCertAuth.pfx | Buffer | | The client certificate file. Required, unless you specify pfxFilePath . |
clientCertAuth.pfxFilePath | String | | The path to client certificate file. Required, unless you specify pfx . |
clientCertAuth.password | String | | The password of client certificate. |
proxy | Object or false | | This parameter is available only in Node.js environment. If you use a proxy, please specify its configuration. To disable proxy and ignore proxy environment variables, please specify false . |
proxy.host | String | | The host of the proxy server. |
proxy.port | Number | | The port of the proxy server. |
proxy.auth | Object | | If the proxy server requires Basic authentication, please specify its username and password. |
proxy.auth.username | String | | The username of Basic authentication for the proxy server. |
proxy.auth.password | String | | The password of Basic authentication for the proxy server. |
userAgent | String | | This parameter is available only in Node.js environment. A User-Agent HTTP header |
featureFlags | Object | | Feature flags that you can configure. See Feature flags. |
socketTimeout | Number | | This parameter is available only in Node.js environment. The socket timeout in milliseconds. |
Authentication
The client supports three authentication methods:
- Password authentication
- API token authentication
- OAuth authentication
- Session authentication
The required parameters inside auth
are different by the methods.
The client determines which method to use by passed parameters.
Name | Type | Required | Description |
---|
username | String | Yes | |
password | String | Yes | |
Name | Type | Required | Description |
---|
apiToken | String or String[] | Yes | You can pass multiple api tokens as an array of string. |
Name | Type | Required | Description |
---|
oAuthToken | String | Yes | An OAuth access token you get through the OAuth process flow. |
Supported in browser environment only.
If you omit auth
parameter, the client uses Session authentication.
Session authentication is available in Garoon customization.
Feature flags
Name | Type | Default | Description |
---|
enableAbortSearchError | boolean | false | An option of whether to throw KintoneAbortSearchError or not. |
Error Handling
See Error Handling
TypeScript
See TypeScript Definitions
References
Contribution Guide
License