garoon-rest

Rest API Client for Garoon

WIP.

Installation

1. Install with npm

This library is distributed on npm.

npm install @miyajan/garoon-rest

You can then use require or import to import the library.

// CommonJS
const { GaroonRestAPIClient } = require("@miyajan/garoon-rest");
// ES modules
import { GaroonRestAPIClient } from "@miyajan/garoon-rest";

2. UMD files (for browser environment)

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

• https://unpkg.com/@miyajan/garoon-rest@latest/umd/GaroonRestAPIClient.js
• minified one: https://unpkg.com/@miyajan/garoon-rest@latest/umd/GaroonRestAPIClient.min.js

After loading this, you can use GaroonRestAPIClient directly. In Garoon customization, please add this URL in "JavaScript and CSS customization" setting.

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.

Usage

Here is a sample code that retrieves a schedule event.

const client = new GaroonRestAPIClient({
  baseUrl: "https://example.cybozu.com/g",
  // Use password authentication
  auth: {
    username: process.env.GAROON_USERNAME,
    password: process.env.GAROON_PASSWORD,
  },
  // Use OAuth token authentication
  // auth: { oAuthToken: process.env.GAROON_OAUTH_TOKEN }

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

client.schedule
  .getEvent({ id: "1" })
  .then((resp) => {
    console.log(resp);
  })
  .catch((err) => {
    console.log(err);
  });

Parameters for GaroonRestAPIClient

Name	Type	Required	Description
baseUrl	String	Conditionally Required	The base URL for your Garoon environment. On cybozu.com, it must end with /g. (e.g. https://example.cybozu.com/g) If you use on-premise Garoon environment, it must end with grn.cgi or grn.exe (e.g. http://example.com/cgi-bin/cbgrn/grn.cgi) Required in Node.js environment. If you omit it in browser environment, the base URL will be determined from location.
auth	Object	Conditionally Required	The object for authentication. See Authentication.
basicAuth	Object		If your Garoon 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.
clientCertAuth	Object		This parameter is available only in Node.js environment. If your Garoon 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		This parameter is available only in Node.js environment. If you use a proxy, please specify its configuration.
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.

Authentication

The client supports three authentication methods:

1. Password authentication
2. OAuth authentication
3. 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 OAuth authentication

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

3. Session authentication

Supported in browser environment only. If you omit auth parameter, the client uses Session authentication.

Error Handling

See Error Handling

References

• Schedule
• Workflow

Contribution Guide

• CONTRIBUTING.md

License

• MIT

Disclaimer

This OSS is my own personal work and does not have any relationship with Cybozu Inc. or any other organization which I belong to.