Skip to content

Commit c501024

Browse files
chihiro-adachiCopilot
chihiro-adachi
and
Copilot
authored
docs(rest): add descriptions of functions and options (#3267)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent f059b1c commit c501024

File tree

1 file changed

+97
-6
lines changed

1 file changed

+97
-6
lines changed

‎packages/rest/README.md

+97-6
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
# @kintone/rest
22

33
[![npm version](https://badge.fury.io/js/@kintone%2Frest.svg)](https://badge.fury.io/js/@kintone%2Frest)
4-
![Node.js version](https://img.shields.io/badge/dynamic/json.svg?url=https://raw.githubusercontent.com/kintone/js-sdk/main/packages/rest/package.json&label=node&query=$.engines.node&colorB=blue)
4+
![Node.js version](https://img.shields.io/badge/node-%3E%3D20-blue)
55
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](LICENSE)
66

77
**@kintone/rest** is a client library for accessing the kintone REST API from JavaScript or TypeScript applications.
88
It is automatically generated using [openapi-typescript](https://github.com/openapi-ts/openapi-typescript).
99

10-
> [!WARNING] **Experimental**: This package is in early development and subject to change.
11-
1210
- [Migration](#migration)
1311
- [Installation](#installation)
12+
- [Browsers support](#browsers-support)
1413
- [Usage](#usage)
15-
- [References](#references)
14+
- [Parameters for `KintoneRest`](#parameters-for-kintonerest)
15+
- [Helper functions](#helper-functions)
1616
- [Contribution Guide](#contribution-guide)
1717
- [License](#license)
1818

@@ -22,6 +22,8 @@ See the [Migration Guide](docs/migration-from-rest-api-client.md).
2222

2323
## Installation
2424

25+
### 1. Install with npm
26+
2527
Install the package via [npm](https://www.npmjs.com/package/@kintone/rest):
2628

2729
```shell
@@ -37,9 +39,27 @@ const { createClient } = require("@kintone/rest");
3739
import { createClient } from "@kintone/rest";
3840
```
3941

40-
## Browser Support
42+
### 2. Load UMD files from CDN (for browser environment)
43+
44+
> [!IMPORTANT]
45+
> To avoid cascading failures from the CDN, we recommend using the npm package and bundling it to your plugin/customization.
46+
47+
You can also load Universal Module Definition (UMD) files directly from Cybozu CDN:
48+
49+
- https://cybozu.dev/ja/kintone/sdk/library/cybozu-cdn/#kintone-rest
50+
51+
Regarding restrictions and availability, please check Cybozu CDN Policy:
52+
53+
- https://cybozu.dev/ja/policy/cybozu-cdn-policy/
4154

42-
TODO
55+
After loading the UMD file, you can use `KintoneRest` in your environment.
56+
In Kintone customization, please add the UMD file URL in the "JavaScript and CSS Customization" setting of your app.
57+
58+
## Browsers support
59+
60+
| [<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/)<br/>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/)<br/>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/)<br/>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/)<br/>Safari |
61+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62+
| Latest version | Latest version | Latest version | Latest version |
4363

4464
## Usage
4565

@@ -82,6 +102,77 @@ try {
82102
We recommend using TypeScript to take advantage of features like path and parameter autocompletion.
83103
If you're using JavaScript, you can still create the client using the same code, though without those benefits.
84104

105+
## Parameters for `KintoneRest`
106+
107+
| Name | Type | Required | Description |
108+
| -------------------------- | :--------------------------------------------------------------: | :-------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
109+
| baseUrl | String | Conditionally<br />Required | The base URL for your Kintone environment.<br />It must start with `https`. (e.g. https://example.kintone.com) <br />Required in Node.js environment. If you omit it in browser environment, `location.origin` will be used.<br />The protocol of baseUrl must be `https` except when hostname is `localhost`. |
110+
| auth | Object | Conditionally<br />Required | The object for authentication. See [Authentication](#Authentication). |
111+
| basicAuth | Object | | If your Kintone environment uses Basic authentication, please specify its username and password. |
112+
| basicAuth.username | String | | The username of Basic authentication. |
113+
| basicAuth.password | String | | The password of Basic authentication. |
114+
| httpsAgent | Object | | **This parameter is available only in Node.js environment.**<br />The custom HTTPS agent to be used when making requests.<br />The agent should be compatible with [undici.Agent](https://github.com/nodejs/undici/blob/main/docs/docs/api/Agent.md). |
115+
| clientCertAuth | Object | | **This parameter is available only in Node.js environment.**<br />**When `httpsAgent` parameter is given, this parameter is unavailable.**<br />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. |
116+
| 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`. |
117+
| 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`. |
118+
| clientCertAuth.password | String | | The password of client certificate. |
119+
| proxy | Object | | **This parameter is available only in Node.js environment.**<br />If you use a proxy, please specify its configuration. |
120+
| proxy.protocol | String | | The protocol of the proxy server. Default is `http`. |
121+
| proxy.host | String | | The host of the proxy server. |
122+
| proxy.port | Number | | The port of the proxy server. |
123+
| proxy.auth | Object | | If the proxy server requires Basic authentication, please specify its username and password. |
124+
| proxy.auth.username | String | | The username of Basic authentication for the proxy server. |
125+
| proxy.auth.password | String | | The password of Basic authentication for the proxy server. |
126+
| userAgent | String | | **This parameter is available only in Node.js environment.**<br />A User-Agent HTTP header |
127+
| socketTimeout | Number | | **This parameter is available only in Node.js environment.**<br />The socket timeout in milliseconds. |
128+
129+
### Authentication
130+
131+
The client supports three authentication methods:
132+
133+
1. [Password authentication](https://kintone.dev/en/docs/common/authentication/#password-authentication)
134+
2. [API token authentication](https://kintone.dev/en/docs/common/authentication/#api-token-authentication)
135+
3. [OAuth authentication](https://kintone.dev/en/docs/common/authentication/how-to-add-oauth-clients/)
136+
4. [Session authentication](https://kintone.dev/en/docs/common/authentication/#session-authentication)
137+
138+
#### 1. Parameters for [Password authentication](https://kintone.dev/en/docs/common/authentication/#password-authentication)
139+
140+
| Name | Type | Required | Description |
141+
| -------- | :----: | :------: | -------------------------- |
142+
| type | String | Yes | Please specify "password". |
143+
| username | String | Yes | |
144+
| password | String | Yes | |
145+
146+
#### 2. Parameters for [API token authentication](https://kintone.dev/en/docs/common/authentication/#api-token-authentication)
147+
148+
| Name | Type | Required | Description |
149+
| -------- | :----------------: | :------: | ------------------------------------------------------- |
150+
| type | String | Yes | Please specify “apiToken”. |
151+
| apiToken | String or String[] | Yes | You can pass multiple api tokens as an array of string. |
152+
153+
#### 3. Parameters for [OAuth authentication](https://kintone.dev/en/docs/common/authentication/how-to-add-oauth-clients/)
154+
155+
| Name | Type | Required | Description |
156+
| ---------- | :----: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
157+
| type | String | Yes | Please specify “oauth”. |
158+
| 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). |
159+
160+
#### 4. [Session authentication](https://kintone.dev/en/docs/common/authentication/#session-authentication)
161+
162+
| Name | Type | Required | Description |
163+
| ---- | :----: | :------: | ------------------------- |
164+
| type | String | Yes | Please specify "session". |
165+
166+
Supported in browser environment only.
167+
If you omit `auth` parameter, the client uses Session authentication.
168+
169+
## Helper functions
170+
171+
### Iterator helper
172+
173+
You can use the iterator to retrieve the API execution results efficiently.
174+
For detailed usage examples, please refer to [https://github.com/kintone/js-sdk/blob/main/packages/rest/src/**tests**/helpers/iterator.test.ts](https://github.com/kintone/js-sdk/blob/main/packages/rest/src/__tests__/helpers/iterator.test.ts).
175+
85176
## Contribution Guide
86177

87178
See [CONTRIBUTING.md](https://github.com/kintone/js-sdk/tree/main/CONTRIBUTING.md) for guidelines on how to contribute to this project.

0 commit comments

Comments
 (0)