Gravio API ドキュメント

APIの使用方法

はじめに

このドキュメントでは、curlを使用した例でGravio REST APIの使用方法を説明します。

リクエストの作成

Gravioがインストールされ、ライセンスが有効であることを確認してください。インストールとライセンスの手順については、Gravioユーザードキュメントを参照してください。HubKitのアカウントが必要です。
パーソナルアクセストークン（PAT）を作成します。HubKitにログインし、リクエスト認証用の最初のPATを生成します。詳細については、認証セクションを参照してください。
エンドポイントを選択し、HTTPメソッド、パス、必要なパラメータ、リクエストペイロードを特定します。
curlコマンドを使用してリクエストを作成します。Authorizationヘッダーにトークンを含め、YOUR-TOKENを実際のトークンに置き換えてください。

リクエスト例

以下の例では、「GetActions」エンドポイントを使用して利用可能なアクションのリストを取得します：

curl --request GET --insecure \
--url "https://your.graviohubkit.com/public/v1/actions" \
--header "Authorization: Bearer YOUR-TOKEN"

ボディパラメータを使用したリクエスト例

この例では、「RunActionSync」エンドポイントを使用して「Today」という名前のアクションを実行します：

curl --request POST --insecure \
--url "https://your.graviohubkit.com/public/v1/action/run" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{"action": "Today"}'

レスポンスの使用

リクエストを作成すると、APIはステータスコード、ヘッダー、およびレスポンスボディを返します。

レスポンスコードとヘッダー

ステータスコードとヘッダーを表示するには、curlリクエストに--includeまたは-iオプションを追加します。

アクション実行成功時のレスポンス例：

HTTP/2 200
content-type: application/json
date: Wed, 05 Feb 2025 09:39:38 GMT
vary: Origin
content-length: 84

{"out":{"ExitCode":0,"Payload":"Hello world!\n","Stderr":""},"success":true,"tv":{}}

HTTPレスポンスステータスコードは、特定のリクエストが正常に完了したかどうかを示します。レスポンスコードは以下のようにカテゴリ分けされます：

200-299: 成功レスポンス
400-499: クライアントエラーレスポンス
500-599: サーバーエラーレスポンス

レスポンスボディ

多くのエンドポイントはレスポンスボディを返します。特に指定がない限り、レスポンスボディはJSON形式です。

エラーレスポンスボディ

APIレスポンスが4xxまたは5xxステータスコードの場合、エラーが発生したことを示します。ボディにはエラーの詳細を説明する以下のフィールドが含まれます：

{
  "Type": "GE_Unauthorized",
  "Title": "Unauthorized",
  "Detail": "Validate provided token: invalid token",
  "Timestamp": "2025-02-05T18:59:17.225722+09:00"
}

タイムスタンプ

返されるタイムスタンプはRFC3339形式です。例：'2025-02-05T11:28:28.485512+09:00'。詳細については、RFC3339 - Date and Time on the Internet: Timestampsを参照してください。

認証

Gravio APIはパーソナルアクセストークン（PAT）を使用してリクエストを認証します。

リクエストを認証するには、認証トークンを提供する必要があります。パーソナルアクセストークンはGravio HubKitで作成・管理できます。トークンを作成した後、Authorization: Bearerを使用してトークンを渡すことでリクエストを認証できます。

すべてのAPIリクエストはHTTPS経由で行う必要があります。HTTPで行われた呼び出しは失敗します。認証なしのAPIリクエストも失敗します。

curl --request GET --insecure \
--url "https://your.graviohubkit.com/public/v1" \
--header "Authorization: Bearer YOUR-TOKEN"

認証失敗時

トークンなし、または無効もしくは期限切れのトークンでREST APIエンドポイントを使用しようとすると、401 Unauthorizedレスポンスが返されます。

レート制限

Gravio HubKitは、特定の時間内に作成できるREST APIリクエストの数を制限しています。この制限は、サービスの安定性を確保するため、悪用やサービス拒否攻撃を防ぐのに役立ちます。

レート制限戦略としてトークンバケット方式が適用されています。IPアドレスごとにバケットあたり100トークンが許可され、1秒あたり10トークンの速度で補充されます。受信したすべてのリクエストは1トークンを消費します。

レート制限超過時

レート制限を超えると、'429 Too Many Requests'レスポンス、コード'GE_Rate_Limit_Exceeded'、およびレート制限を超えたことを示すエラーメッセージが返されます。

'GE_Rate_Limit_Exceeded'エラーのレスポンスボディには、現在のレート制限を1秒あたりのレート数として示すLimit拡張が含まれます：

{
  "Type": "GE_Rate_Limit_Exceeded",
  "Title": "Rate limit exceeded",
  "Detail": "You are being rate-limited. Retry after some time to continue using the service.",
  "Extensions": {
    "Limit": 10
  },
  "Timestamp": "2025-02-05T19:25:21.105904+09:00"
}