Skip to content
Last updated

English version

はじめに

このリファレンスサイトは、LegalOn の RESTful API についてのリファレンスサイトです。

アクセストークンの取得と API コール

LegalOn の API は OAuth 2.0 Client Credentials Flow に準拠しており、grant_type=client_credentials を指定してアクセストークンをリクエストします。

アクセストークン取得と API 利用の流れ

  1. クライアントから、API クレデンシャルを利用して、アクセストークン取得のためのリクエストを行います
  2. リクエストが成功すると、認可サーバーからアクセストークンが返却されます
  3. アクセストークンを利用して、リソースサーバー(LegalOn API)へ API コールを行います
  4. API コールが成功すると、リソースサーバーからレスポンスが JSON 形式で返却されます

API利用の流れ

クレデンシャルの取得

API クレデンシャルは LegalOn の管理画面から取得できます。
[個人設定] => [API連携]画面から取得を行なってください。
API クレデンシャルを発行する際は、以下の項目を入力します

  • 管理用の表示名
    • API クレデンシャル管理のための表示名を入力します
  • 有効期限
    • API クレデンシャルの有効期限です。以下から選択します
      • 7 日
      • 30 日
      • 60 日
      • 日単位での期限指定
      • 無期限

登録後、発行された API クレデンシャルが表示されます。 API クレデンシャルは発行時のみしか表示されないため、ご注意ください。

API コールの補足

  • ${サーバーURL} の値は LegalOn を契約されているリージョンによって異なります。 リージョンは LegalOn の管理者設定のライセンスの画面から確認できます。 管理者設定のメニューが表示されない場合は、テナントの管理者にお問い合わせください。
    • JPリージョン: https://public-api.legalon-cloud.com
    • USリージョン: https://public-api.legalontech.com
  • リクエストヘッダには必ず Authorization と Content-Type を指定してください。

サンプルコード

API クレデンシャルを利用して、API をコールするためのアクセストークンを取得するサンプルコードです。

curl

curl -H "Authorization: Basic ${APIクレデンシャル}" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -X POST ${サーバーURL}/oauth/token

レスポンス例

アクセストークンのリクエストに成功すると、以下のようなレスポンスが取得できます。 取得した ${APIのベースURL} と ${アクセストークン} を利用して API のコールを行います。 アクセストークンの有効期限は、発行後 1200 秒(20 分)です。なおこの有効期限は変更される可能性があります。

{
  "access_token": "${アクセストークン}",
  "expires_in": 1200,
  "token_type": "Bearer",
  "api_base_url": "${APIのベースURL}",
}

API の呼び出し方法

クライアントアプリケーションから API 用アクセストークンおよび必要なリクエストパラメータを指定することで、公開 API を呼び出すことができます。

リクエスト例

curl -X POST \
     -H "Authorization: Bearer ${アクセストークン}" \
     -H "Content-Type: application/json" \
     -d '<対象APIのリクエストパラメータ>' \
     ${APIのベースURL}/<対象APIのパス>

レスポンスの取得

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

正常時

対象 API に定義された ステータスコード および レスポンスボディ が返されます。 なお、レスポンスボディは拡張される可能性がありますので、未知の JSON フィールドを読み飛ばして処理できるように実装してください。

エラー時

原因に応じた ステータスコード および エラーメッセージ が返されます。

例：

  • 無効なアクセストークン
  • パラメータの不備
  • 権限不足 など

共通レスポンスヘッダ

以下のヘッダは、リクエストを行なって際に取得できます。

  • X-RateLimit-Limit
    • 設定されているリクエスト上限数
  • X-RateLimit-Remaining
    • 残りのリクエスト可能数
  • X-RateLimit-Reset
    • リクエスト制限がリセットまでの秒数
  • X-Request-Id
    • 各リクエストを一意に識別する ID

利用制限（Rate Limit）

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

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

以下の場合を除き、すべてのリクエストが Rate Limit のカウント対象となります。

除外されるケース：

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

注意:

リクエストが失敗した場合でも、リクエスト条件（権限、パラメータ、リソース状態など）を満たしていないことが原因のエラーであれば、有効な呼び出しとしてカウントされます。

FAQ（よくある質問）

  • Q1. アクセストークンの有効期限が切れた場合はどうすればよいですか？
    • A. 再度 API クレデンシャルを用いてリクエストを行い、新しいアクセストークンを取得してください。リフレッシュトークンは提供されません。
  • Q2.. アクセストークンに含まれる「permissions」はどのように決まりますか？
    • A. API クレデンシャルを紐づけたユーザーが持つ権限に基づきます。将来的には、API クレデンシャル発行時に選択した権限のみを反映できるようになる予定です。
  • Q3. 短時間で多数のリクエストを送信するとどうなりますか？
    • A. Rate Limit（利用回数制限）を超過するとリクエストが拒否される場合があります。
 
Next page