Garoon REST APIは、スケジュールやワークフローなどのGaroonのデータを操作できるAPIです。
このページでは、Garoon REST APIの共通仕様を説明します。
各APIの仕様の詳細は、それぞれのAPIのページを確認してください。

APIによって異なります。

リソースは、APIによって異なります。
詳細は各APIのページを確認してください。

クラウド版

https://sample.cybozu.com/g/api/v1/APPLICATION_NAME/RESOURCE

パッケージ版

それぞれヘルプに記載しているディレクトリ構成（ Windows ｜ Linux ）でインストールしたときの例です。
インストールするディレクトリを変更している場合は、パスを読み替えてください。

Windows環境

http://IP_ADDRESS_OR_HOST_NAME/scripts/INSTALL_IDENTIFER/grn.exe/api/v1/APPLICATION_NAME/RESOURCE

Linux環境

http://IP_ADDRESS_OR_HOST_NAME/cgi-bin/INSTALL_IDENTIFER/grn.cgi/api/v1/APPLICATION_NAME/RESOURCE

送信するリクエストに応じて次のリクエストヘッダーを指定します。
Garoon REST APIリクエストを送信するAPI を使ってGaroon REST APIを実行する場合には、リクエストヘッダーの指定は不要です。

Host

Garoon REST APIを実行するドメインとポート番号（443）を、「ドメイン:ポート番号」の形式で指定します。
Hostは必須です。

Content-Type

「application/json」を指定します。
リクエストボディの形式がJSON文字列の場合のみ指定します。

X-Cybozu-Authorization

「ログイン名:パスワード」をBase64エンコードした値を指定します。
パスワードを使って認証する場合のみ指定します。
パスワード認証

X-Requested-With

「XMLHttpRequest」または空文字列以外の文字列を指定します。
セッションで認証する場合のみ指定します。
セッション認証

Authorization

次の値を半角スペースで結合した値を指定します。

• Basic
• 「Basic認証のユーザー名:Basic認証のパスワード」をBase64エンコードした値

Basic認証を設定している場合のみ指定します。
Basic認証を設定している環境

JSON形式で指定します。文字コードはUTF-8です。

JSON文字列でエスケープが必要な文字は、\でエスケープしてください。

GETメソッドのAPIでは、URLのクエリパラメーターとしてリクエストパラメーターを付与し、リクエストを送信できます。
たとえばリクエストパラメーターのlimitが「100」の場合、クエリパラメーターは次のように指定します。

1

/g/api/v1/schedule/events?limit=100

エスケープ

URLの仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「name=cybozu#」をパーセントエンコーディングした例です。

1

/g/api/v1/base/users?name=cybozu%23

配列型のパラメーターを指定する場合

配列を要素に分解してパーセントエンコーディングします。

リクエストパラメーターのcodesに、「会議室」と「Zoom」を指定する例を示します。

1. codes=[会議室,Zoom]という配列を要素に分解します。

   1	/g/api/v1/schedule/admin/facilities?codes[0]=会議室&codes[1]=Zoom

2. クエリパラメーターのキーや値をパーセントエンコーディングします。

   1	/g/api/v1/schedule/admin/facilities?codes%5B0%5D=%E4%BC%9A%E8%AD%B0%E5%AE%A4&codes%5B1%5D=Zoom

リクエストに成功した場合、200番台のステータスコードが返ります。
リクエストに失敗した場合、200番台以外のステータスコードとエラーレスポンスが返ります。
エラーレスポンス

X-ConcurrencyLimit-Limit

同時接続数の上限値です。
必ず100が返ります。

X-ConcurrencyLimit-Running

現在の同時接続数です。

JSON形式で返されます。文字コードはUTF-8です。

次のプロパティをもつオブジェクトがJSON形式で返されます。

パラメーター名	型	説明
errorCode	文字列	エラーの種類を表すコード 詳細は、ヘルプ（ クラウド版 ／ パッケージ版 ）を参照してください。
message	文字列	エラーメッセージ 出力されるメッセージの言語は、APIを実行したユーザーの 表示言語の設定 によって異なります。
cause	文字列	エラーの原因 出力されるメッセージの言語は、APIを実行したユーザーの 表示言語の設定 によって異なります。

エラーの例

1
2
3
4
5

{
  "errorCode": "GRN_REST_API_00208",
  "message": "入力内容が正しくありません。",
  "cause": "nameが最小文字数より小さいです。"
}

同時にリクエストできるAPIは、1ドメインにつき100までです。
上限を超えるアクセスがあった場合、利用を制限させていただく場合がございます。

短時間に大量のAPIリクエストを連続して実行すると、サーバーへの負荷や処理の遅延につながる可能性があります。
特に、通知や関連する処理が発生するAPIを連続して実行する場合は、リクエスト間に一定の間隔を設けるなど、実行頻度の調整を推奨します。

添付ファイルをアップロードする場合、アップロードできるファイルサイズの上限は、Base64エンコードした後の値で300MBまです。
Garoonのシステム設定で、ファイルサイズの上限を「無制限」に設定した場合も同様です。

サービスに関する制限事項は、 サイボウズのクラウドサービス制限事項 を参照してください。