Garoon REST API の概要

目次

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

リクエスト

HTTP メソッド

API によって異なります。

URL

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

クラウド版

https://sample.cybozu.com/g/api/v1/アプリケーション名/リソース

パッケージ版

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

Windows 環境
http://サーバーの IP アドレスまたはホスト名/scripts/インストール識別子/grn.exe/api/v1/アプリケーション名/リソース
Linux 環境
http://サーバーの IP アドレスまたはホスト名/cgi-bin/インストール識別子/grn.cgi/api/v1/アプリケーション名/リソース

リクエストヘッダー

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

パラメーター名 必須 説明
Host 必須 sample.cybozu.com:443
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

レスポンス

HTTP ステータスコード

リクエストに成功した場合、200 番台のステータスコードが返ります。
リクエストに失敗した場合、200 番台以外のステータスコードと次のプロパティをもつオブジェクトが返ります。

パラメーター名 説明
errorCode 文字列 エラーの種類を表すコード
詳細は、ヘルプ( クラウド版 (External link) パッケージ版 (External link) )を参照してください。
message 文字列 エラーメッセージ
出力されるメッセージの言語は、API を実行したユーザーの 表示言語の設定 (External link) によって異なります。
cause 文字列 エラーの原因
出力されるメッセージの言語は、API を実行したユーザーの 表示言語の設定 (External link) によって異なります。
エラーの例
1
2
3
4
5
{
  "errorCode": "GRN_REST_API_00208",
  "message": "入力内容が正しくありません。",
  "cause": "nameが最小文字数より小さいです。"
}

レスポンスヘッダー

ヘッダー名 内容
X-ConcurrencyLimit-Limit 同時接続数の上限値
必ず 100 が返ります。
X-ConcurrencyLimit-Running 現在の同時接続数

レスポンスボディ

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

制限事項

同時接続数

同時にリクエストできる API は、1 ドメインにつき 100 までです。

添付ファイルのアップロード

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

その他の制限事項

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