Garoon REST APIの共通仕様 – cybozu developer network

次期Garoon REST APIに関するアンケートにご協力ください。

Index

Garoon REST APIの概要
ユーザー認証
Basic認証
リクエスト
レスポンス
注意事項
制限事項

Garoon REST APIの概要

Garoon のデータを取得、登録、更新、削除することができます。

プロトコル

HTTPS

フォーマット

JSON

文字コード

UTF-8

エスケープ文字

「\」を使用します。

ユーザー認証

APIを実行するリクエストには、認証のためのヘッダを追加する必要があります。

パスワード認証

リクエストヘッダに「X-Cybozu-Authorization」を追加し、「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
X-Cybozu-Authorization:QWRtaW5pc3RyYXRvcjpjeWJvenU=

セキュアアクセス設定環境にログインしたユーザーが、ログインユーザーと異なるユーザーの認証情報を使って JavaScript カスタマイズでの REST API を実行する場合、設定が必要です。
利用するには「.com 共通管理」より「証明書のユーザーとパスワード認証のユーザーが異なるアクセスを許可する」を有効にしてください。

セッション認証

セッション認証とは、Webサーバから付与されたセッションIDをCookieに保存する事でユーザを識別する認証方法です。
※ POST、PATCH、DELETEでは、セッション認証の場合は、RequestTokenが必要です。詳しくは Garoon CSRFトークンの利用例の記事をご確認ください。

認証時の優先順位について

優先順位は以下の通りです。

パスワード認証
セッション認証

OAuthクライアントを使用して認証することも出来ます。詳細はこちらを参照してください。

SAML認証設定時の利用について

SAML認証設定時に、cybozu.comのパスワード認証でGaroon REST APIを利用できます。
cybozu.com のログイン時に SAML 認証のみを使うように制限している場合、パスワード認証による Garoon REST API の実行がcybozu.com共通管理者のみに制限されます。

Basic認証

cybozu.com でBasic認証を利用している場合は、更にリクエストヘッダに「Authorization」ヘッダを追加し、「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

「Basic」と「ログイン名:パスワード」の間は、半角空白が必要です。
「Basic」の BASE64エンコードは不要です。

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
Authorization:Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

リクエスト

リクエストヘッダ

送信するリクエストに応じて以下のリクエストヘッダを指定します。

ヘッダー名	必須	内容
Host	必須	(サブドメイン名).cybozu.com:443
Content-Type	省略可	application/json ※リクエストボディにJSON文字列を格納する場合のみ指定します。
X-Cybozu-Authorization	省略可 ※パスワード認証を利用している場合必須	「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。
X-Requested-With	省略可 ※セッション認証を利用している場合必須	XMLHttpRequest または空文字列以外の文字列
Authorization	省略可	Basic認証を利用している場合、文字列「Basic」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。

リクエストURI

クラウド版

https://(サブドメイン名).cybozu.com/g/api/v1/(アプリケーション名)/(リソース)

パッケージ版（Windows環境）

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

パッケージ版（Linux環境）

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

レスポンス

HTTPステータスコードが「2xx」であれば正常終了、それ以外はエラー終了です。

エラーの詳細については、 Garoon ヘルプ - エラーメッセージ一覧　クラウド版・パッケージ版をご参照ください。

すべてのGaroon REST APIのレスポンスヘッダには、次の情報が含まれています。

ヘッダー名	内容
X-ConcurrencyLimit-Limit	同時接続数の上限値固定値の100です。
X-ConcurrencyLimit-Running	現在の同時接続数

garoon.api()でリクエストした場合のレスポンスについて

garoon.api()でGaroon REST APIをリクエストした際、コールバックに渡される情報はレスポンスボディのみです。
そのため、レスポンスボディ以外の情報を利用する場合はgaroon.api()以外でリクエストする必要があります。

注意事項

IPアドレス制限を行っている環境に対するREST APIリクエストについては、次のAPIリクエストがアクセス可能です。

アクセス許可されたIPアドレスがアクセス元となるAPIリクエスト
アクセス許可されたクライアント証明書を利用したAPIリクエスト

制限事項

Garoon REST APIの同時実行制限があります。それはREST API要求だけがカウントされます。デフォルト値は100です。

その他、サービスに関する制限事項は、cybozu.comの制限事項をご確認ください。