# 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/master/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. 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`](https://unpkg.com/@kintone/rest-api-client@1.0.0/umd/KintoneRestAPIClient.js). ## Browsers support | [Edge](http://godban.github.io/browsers-support-badges/)
Edge | [Firefox](http://godban.github.io/browsers-support-badges/)
Firefox | [Chrome](http://godban.github.io/browsers-support-badges/)
Chrome | [Safari](http://godban.github.io/browsers-support-badges/)
Safari | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Latest version | Latest version | Latest version | Latest version | ## Usage Here is a sample code that retrieves records of an app. ```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 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](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/master/packages/rest-api-client/docs/errorHandling.md) ## TypeScript See [TypeScript Definitions](https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client/docs/typescript.md) ## References - [Record](https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client/docs/record.md) - [App](https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client/docs/app.md) - [File](https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client/docs/file.md) - [BulkRequest](https://github.com/kintone/js-sdk/tree/master/packages/rest-api-client/docs/bulkRequest.md) ## Contribution Guide - [CONTRIBUTING.md](https://github.com/kintone/js-sdk/tree/master/CONTRIBUTING.md) ## License - [MIT](https://github.com/kintone/js-sdk/tree/master/LICENSE)