API で外部ツールを連携する
API を使うと、外部のアプリケーションからお客様の Organization のデータ（会員情報、Calendar、Booking、Billing）にプログラム経由でアクセスできます。有効化はわずか 2 クリックで完了し、キー、許可 IP アドレスのリスト、利用状況のモニタリングによって保護されます。
API が必要かどうかを判断する
API は Organization の Manager ではなく、開発者向けの機能です。独自に開発または設定するソフトウェア（オーダーメイドの Web サイト、会計ソフト、自作の表示用ディスプレイ、他システムとの連携ゲートウェイなど）とお客様のアカウントを連携させるために使います。
会員一覧の取得、Subscription の一括更新、事務局への数値の提出といった日常的な用途であれば、インポート、エクスポート、レポートの各機能で対応できます。コードを 1 行も書く必要はありません。
API はベータ版として提供しています。仕様は今後変更される可能性があります。
API を有効化してキーを取得する
- 管理›設定›API BETA を開きます。
- APIモジュールを有効化する を有効にし、保存 をクリックします。
- APIキー が表示されます。コピー ボタンでコピーし、連携するツールにのみ渡してください。
キーは、各リクエストの HTTP ヘッダー X-API-Key で送信します。通信は必ず HTTPS で行ってください。暗号化されていないリクエストは受け付けられません。
キーを保護する
キーを利用するツールや業者に対しては、次の点を改めて確認しておきましょう。
- キーをコードリポジトリに置かないこと。リポジトリ外の設定ファイル、またはシークレット管理ツールに保存します。
- ツールが固定のサーバーから呼び出す場合は、許可する IP アドレスを制限すること。
- 少しでも疑わしい状況（誤って公開した、ログが流出した、業者との契約が終了した）があれば、キーを再生成すること。
再生成する ボタンは確認を求めたうえで、旧キーを即座に無効化します。旧キーを使っていたすべてのアプリケーションは、新しいキーを受け取るまで動作しなくなります。クリックする前に必ず関係者へ知らせてください。
IP アドレスでアクセスを制限する
IPアドレスによる制限 を有効にすると、リストに登録した IP アドレスからのリクエストのみが受け付けられます。登録できるのは IPv4 アドレス 10 件までです。各アドレスを入力し、追加 で確定します。参考として、現在お使いのアドレスが画面に表示されます。
これは最も効果的でありながら、最も見落とされやすい保護策です。万一キーが流出しても、業者のアドレスに限定されていれば、他の場所からは使えません。
利用状況を確認する
画面には、キーの消費状況が常に表示されます。
- この分の使用 と 今日の利用状況。上限が設定されている場合は、それぞれの上限に対する割合も示されます。
- 利用統計：今週、今月、合計、最後のリクエスト。
表示された上限を超えると、追加のリクエストは一時的に拒否されます。カウンターが常に上限付近にある場合は、たいていツールの設定に問題があります。データをキャッシュせず、同じデータを繰り返し要求している状態です。
最終リクエストの日付は逆の意味で役立ちます。有効化したまま数か月間まったく呼び出されていないキーは、無効化すべきキーです。
API でできることを知る
パラメーターや呼び出し例を含む完全なドキュメントは、モジュール画面の下部に表示されます。概要は次のとおりです。
- User：変更が可能な唯一のリソースです。アカウントの一覧取得、参照、作成、変更、削除ができます。
- Configuration：Subscription、プロフィール、グループ、年齢カテゴリーは参照のみ可能で、設定はアプリケーションからのみ行えます。
- Booking：Calendar、空いている Time Slot、Booking、Label は参照のみ可能です。
- Billing：Billing account、Order、支払いは参照のみ可能です。
