Skip to content
Last updated

English version

はじめに

LegalOn API は RESTful API です。利用開始までの流れは次の3ステップです。

  1. APIクレデンシャルを発行（管理画面）
  2. アクセストークンを取得（OAuth 2.0 Client Credentials）
  3. APIを呼び出す（{api_base_url}/rest/v1 に対してリクエスト）

API利用の流れ

重要：

  • トークン取得のエンドポイントは契約リージョンにより異なります。
  • API呼び出しのベースURLは、トークン取得レスポンスに含まれる api_base_url を使って組み立てます（OpenAPI の Servers に従い …/rest/v1 を付与）。

APIクレデンシャルの取得

取得方法

API クレデンシャルは LegalOn の管理画面から発行できます。

発行時に入力する項目

項目説明入力例/選択肢
管理用の表示名API クレデンシャルを管理するための名称です。用途が分かる名前を付けてください。prod-batch-integration / stg-test-client
有効期限API クレデンシャルの有効期限です。運用方針に合わせて選択してください。7日 / 30日 / 60日 / 日単位指定 / 無期限

運用のヒント
本番用のクレデンシャルは「用途＋環境」が分かる表示名にすると、棚卸しや失効時の影響範囲確認が容易になります。

発行後の注意

発行完了後、API クレデンシャルが画面に表示されます。
API クレデンシャルは発行時にのみ表示され、再表示できません。
表示された内容は必ず安全な場所に保管してください。

アクセストークンの取得

取得方法

アクセストークンは OAuth 2.0 の Client Credentials Flow を用いて取得します。

サンプルコード（curl）

curl -H "Authorization: Basic ${APIクレデンシャル}" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -X POST ${api_base_url}/oauth/token
  • ${api_base_url} はリージョンで異なります。
  • ${APIクレデンシャル} は管理画面で発行した値を使用します。

レスポンスの取得

アクセストークンのリクエストに成功すると、以下のレスポンスが返ります。

次に行うこと

  • 以降の API 呼び出しでは、access_token を Authorization: Bearer <access_token> として送信します。
  • API のベースURLには、レスポンスに含まれる api_base_url を使用します（以降は {api_base_url}/rest/v1 を基点にします）。

有効期限について
アクセストークンの有効期限は発行後 1200秒（20分） です。
この値は将来的に変更される可能性があります。実装ではレスポンスボディの expires_in の値を参照してください。

レスポンスボディ（例）

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 1200,
  "token_type": "Bearer",
  "api_base_url": "https://${api_base_url}"
}

フィールド説明

フィールド型説明
access_tokenstringAPI 呼び出しに使用するアクセストークン
expires_innumberトークンの有効期限（秒）
token_typestringトークン種別（通常 Bearer）
api_base_urlstringAPI のベースURL（以降の呼び出しで使用）

API コール時の補足

  • アクセストークンは短命です。401 Unauthorized が返った場合は、まずトークンの再取得を行ってください。
  • 権限（permissions）は API クレデンシャルに紐づくユーザーの権限に基づいて決まります（詳細は FAQ を参照）。
  • レスポンスに X-Request-Id が含まれる場合があります。問い合わせ時やログ調査のため、アプリケーションログに残すことを推奨します。

APIの呼び出し

API呼び出し方法

API のベースURLは {api_base_url}/rest/v1 です（api_base_url はトークン取得レスポンスの値を使用）。

サンプルコード

curl -X GET \
  -H "Authorization: Bearer ${アクセストークン}" \
  -H "Content-Type: application/json" \
  ${api_base_url}/rest/v1/users?page_size=50

レスポンスの取得

API 呼び出しの結果に応じて、以下のレスポンスが返ります。

正常時（2xx）

  • 対象 API に定義された ステータスコード と レスポンスボディ が返ります。

実装上の注意（Forward compatibility）
レスポンスボディは将来的にフィールドが追加される可能性があります。
**仕様に記載されていない JSON フィールドを受信しても処理を継続できるように実装してください。。

エラー時（4xx / 5xx）

  • 原因に応じた ステータスコード と エラー情報 が返されます。

例（代表的なエラー要因）

  • 無効なアクセストークン（例：401 Unauthorized）
  • パラメータ不備（例：400 Bad Request）
  • 権限不足（例：403 Forbidden）
  • Rate Limit 超過（例：429 Too Many Requests）

共通レスポンスヘッダ

以下のヘッダーは API レスポンスに含まれる場合があります。

ヘッダー説明
X-RateLimit-Limit設定されているリクエスト上限数
X-RateLimit-Remaining残りのリクエスト可能数
X-RateLimit-Resetリクエスト制限がリセットされるまでの秒数
X-Request-Id各リクエストを一意に識別する ID（問い合わせ時に使用）

運用のヒント
429 Too Many Requests が返った場合は、X-RateLimit-Reset を目安に待機して再試行してください。
問い合わせの際は X-Request-Id を添えてください。

利用制限（Rate Limit）

API の呼び出し回数には制限があります。上限を超えると、HTTP ステータスコード 429 Too Many Requests が返されます。

カウント対象となるリクエスト

原則として、すべてのリクエストが Rate Limit のカウント対象です。

除外されるケース：

以下のケースではカウント対象外となります。

  • 公開 API 全体のサービスが停止している場合
  • API 用アクセストークンが無効な場合
  • API 用アクセストークンの有効期限が切れている場合
  • すでに Rate Limit 超過エラー（429）を返している場合

注意:

注意（重要）
リクエストが失敗した場合でも、権限不足・パラメータ不備・リソース状態など、
リクエスト条件を満たしていないことが原因で返るエラーは 有効な呼び出しとしてカウントされます。

FAQ（よくある質問）

アクセストークンの有効期限が切れた場合はどうすればよいですか？
アクセストークンが失効した場合は、APIクレデンシャルを用いて再度トークン取得リクエストを送信し、新しいアクセストークンを取得してください。

  • リフレッシュトークンは提供していません。
  • 401 Unauthorized が返った場合は、まずトークンの再取得をお試しください。

アクセストークンに含まれる permissions はどのように決まりますか？
permissions は、APIクレデンシャルに紐づくユーザーの権限に基づいて決まります。

  • 将来的には、APIクレデンシャル発行時に選択した権限のみをトークンに反映できるようにする予定です。

短時間で多数のリクエストを送信するとどうなりますか？
短時間に大量のリクエストを送ると、**Rate Limit（利用回数制限）によりリクエストが拒否（例：429 Too Many Requests）**される場合があります。

  • レスポンスヘッダー（X-RateLimit-*）を参照し、待機・再試行してください。
 
Next page