@kintone/rest-api-client

# kintone-rest-api-client [![npm version](https://badge.fury.io/js/%40kintone%2Frest-api-client.svg)](https://badge.fury.io/js/%40kintone%2Frest-api-client) ![Node.js version](https://img.shields.io/badge/dynamic/json.svg?url=https://raw.githubusercontent.com/kintone/js-sdk/main/packages/rest-api-client/package.json&label=node&query=$.engines.node&colorB=blue) ![License](https://img.shields.io/npm/l/@kintone/rest-api-client.svg) API client for Kintone REST API. It supports both browser environment (Kintone customization & plugin) and Node.js environment. - [Installation](#installation) - [Browsers support](#browsers-support) - [Usage](#usage) - [Parameters for `KintoneRestAPIClient`](#parameters-for-kintonerestapiclient) - [Error Handling](#error-handling) - [TypeScript](#typescript) - [References](#references) - [Contribution Guide](#contribution-guide) - [License](#license) ## Installation ### 1. Install with `npm` This library is distributed on `npm`. ```shell npm install @kintone/rest-api-client ``` You can then use `require` or `import` to import the library. ```javascript // CommonJS const { KintoneRestAPIClient } = require("@kintone/rest-api-client"); // ES modules import { KintoneRestAPIClient } from "@kintone/rest-api-client"; ``` ### 2. Load UMD files from CDN (for browser environment) > [!IMPORTANT] > To avoid cascading failures from the CDN, we recommend using the npm package and bundling it to your plugin/customization. You can also load Universal Module Definition (UMD) files directly from Cybozu CDN: - https://cybozu.dev/ja/kintone/sdk/library/cybozu-cdn/#kintone-rest-api-client Regarding restrictions and availability, please check Cybozu CDN Policy: - https://cybozu.dev/ja/policy/cybozu-cdn-policy/ After loading the UMD file, you can use `KintoneRestAPIClient` in your environment. In Kintone customization, please add the UMD file URL in the "JavaScript and CSS Customization" setting of your app. ## Browsers support | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt="Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) Edge | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) Firefox | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) Chrome | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) Safari | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Latest version | Latest version | Latest version | Latest version | ## Usage Here is a sample code that retrieves app records. ```js 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](#Authentication). | | guestSpaceId | Number or String | | The guest space ID. If you are dealing with guest space or apps in guest space, 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](https://nodejs.org/api/https.html#class-httpsagent). | | 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](https://jp.cybozu.help/general/en/admin/list_security/list_access/secureaccess.html), please specify the certificate file and password. | | clientCertAuth.pfx | [Buffer](https://nodejs.org/api/buffer.html#buffer_class_buffer) | | The [client certificate file](https://jp.cybozu.help/general/en/user/list_access/remote/webbrowser.html). Required, unless you specify `pfxFilePath`. | | clientCertAuth.pfxFilePath | String | | The path to [client certificate file](https://jp.cybozu.help/general/en/user/list_access/remote/webbrowser.html). 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.protocol | String | | The protocol of the proxy server. Default is `http`. | | 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](#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: 1. [Password authentication](https://kintone.dev/en/docs/common/authentication/#password-authentication) 2. [API token authentication](https://kintone.dev/en/docs/common/authentication/#api-token-authentication) 3. [OAuth authentication](https://kintone.dev/en/docs/common/authentication/how-to-add-oauth-clients/) 4. [Session authentication](https://kintone.dev/en/docs/common/authentication/#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](https://kintone.dev/en/docs/common/authentication/#password-authentication) | Name | Type | Required | Description | | -------- | :----: | :------: | ----------- | | username | String | Yes | | password | String | Yes | #### 2. Parameters for [API token authentication](https://kintone.dev/en/docs/common/authentication/#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](https://kintone.dev/en/docs/common/authentication/how-to-add-oauth-clients/) | Name | Type | Required | Description | | ---------- | :----: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | oAuthToken | String | Yes | An OAuth access token you get through the [OAuth process flow](https://kintone.dev/en/docs/common/authentication/how-to-add-oauth-clients/#authorization-code-grant-flow). | #### 4. [Session authentication](https://kintone.dev/en/docs/common/authentication/#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](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/errorHandling.md) ## TypeScript See [TypeScript Definitions](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/typescript.md) ## References - [Record](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/record.md) - [App](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/app.md) - [Space](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/space.md) - [File](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/file.md) - [BulkRequest](https://github.com/kintone/js-sdk/tree/main/packages/rest-api-client/docs/bulkRequest.md) ## Contribution Guide - [CONTRIBUTING.md](https://github.com/kintone/js-sdk/tree/main/CONTRIBUTING.md) ## License - [MIT](https://github.com/kintone/js-sdk/tree/main/LICENSE)