@kintone/rest-api-client

kintone-rest-api-client

API client for Kintone REST API. It supports both browser environment (Kintone customization & plugin) and Node.js environment.

• Installation
• Browsers support
• Usage
• Parameters for KintoneRestAPIClient
• Error Handling
• TypeScript
• References
• Contribution Guide
• License

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.

// CommonJS
const { KintoneRestAPIClient } = require("@kintone/rest-api-client");
// ES modules
import { KintoneRestAPIClient } from "@kintone/rest-api-client";

2. UMD files (for browser environment)

This library also provides two Universal Module Definition (UMD) files:

• https://unpkg.com/@kintone/rest-api-client@latest/umd/KintoneRestAPIClient.js
• minified one: https://unpkg.com/@kintone/rest-api-client@latest/umd/KintoneRestAPIClient.min.js

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",
  // Use password authentication
  auth: {
    username: process.env.KINTONE_USERNAME,
    password: process.env.KINTONE_PASSWORD,
  },
  // Use API token authentication
  // auth: { apiToken: process.env.KINTONE_API_TOKEN }
  // Use OAuth token authentication
  // auth: { oAuthToken: process.env.KINTONE_OAUTH_TOKEN }

  // Use session authentication if `auth` is omitted (in browser only)
});

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.

Authentication

The client supports three authentication methods:

1. Password authentication
2. API token authentication
3. OAuth authentication
4. Session authentication

The required parameters inside auth are different by the methods. The client determines which method to use by passed parameters.

1. Parameters for Password authentication

Name	Type	Required	Description
username	String	Yes
password	String	Yes

2. Parameters for API token authentication

Name	Type	Required	Description
apiToken	String or String[]	Yes	You can pass multiple api tokens as an array of string.

3. Parameters for OAuth authentication

Name	Type	Required	Description
oAuthToken	String	Yes	An OAuth access token you get through the OAuth process flow.

4. Session authentication

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

• Record
• App
• File
• BulkRequest

Contribution Guide

• CONTRIBUTING.md

License

• MIT