kintone-rest-api-client

!Node.js version
!License

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

$3

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";
`

$3

> [!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

|
Edge |
Firefox |
Chrome |
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. |
| 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. |
| 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.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. |
| socketTimeout | Number | | This parameter is available only in Node.js environment.
The socket timeout in milliseconds. |

$3

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.

$3

| 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
- Space
- File
- BulkRequest

Contribution Guide

- CONTRIBUTING.md

License

- MIT