API リファレンス
API操作を使用し、その結果を解釈してください
利用可能なエンドポイント、冪等性ルール、キューに入れられたアクションの応答、操作追跡の現在の制限を読んでください。
始める前に
- 有効なセッションと、保護された変更の場合はそのCSRFトークン。
- 現在のカタログまたは認証されたAPI応答から取得した識別子。
- 各注文、引き出し、またはハードウェアアクションに対する一意の Idempotency-Key。
変更する前にアカウントを読む
読み取りエンドポイントを使用して、アカウント、残高、対象リソースを確認してください。GET /api/v1/meはユーザー名、balanceUsd、セッションのcsrfTokenを返します。リソース識別子はアカウント固有です。別の環境から値をコピーせずに、現在のアカウントに対して返されたサーバーまたはネットワーク識別子を使用してください。
現在の API はコンパクトなアカウントインターフェースであり、完全な非同期ジョブプラットフォームではありません。成功した書き込みからの参照を自分の記録に保存してください。すべての注文を一覧表示したり、特定のキュー内アクションを検査したり、引き出しの最新のレビューステータスを取得したりするエンドポイントはありません。
| エンドポイントを読み取る | 返されたデータ |
|---|---|
| GET /api/v1/ledger | 最新の 100 台帳エントリ、新しい順。ページネーション契約はありません。 |
| GET /api/v1/servers | 終了していないサーバー、状態、リージョン、paidThrough、graceUntil、autoRenew。 |
| GET /api/v1/network | 割り当てられたアドレス、プレフィックス長、PTR値、関連するサーバー識別子。 |
| GET /api/health | 基本サービスとカタログ数。アカウントまたは物理サーバーの健全性保証はありません。 |
一致する変更エンドポイントを使用する
サポートされているサーバーアクションは、再起動、power_off、再インストール、mount_iso、kvm、およびrotate_root_passwordです。カスタムISO URLは、埋め込み資格情報なしでパブリックHTTPSを使用する必要があります。注文期間は週次または月次で、7日または30日を表します。価格、割引、資金、および容量はサービスによってチェックされます。クライアントが計算した価格を権威として送信しないでください。
| エンドポイント | リクエストフィールドと結果 |
|---|---|
| POST /api/v1/orders | configId、regionId、osId、term、quantity；オプションのsshPublicKey。注文IDとACCEPTEDを返します。 |
| POST /api/v1/deposit-addresses | 資産。返却アドレス、資産、ネットワーク、必要な確認数、モード、または決済不可エラーを返します。 |
| POST /api/v1/withdrawals | asset, destination, usd。idとPENDING_REVIEWを返し、残高は保留されます。 |
| POST /api/v1/servers/{id}/actions | action; mount_isoのisoUrl。アクションIDとQUEUEDを返します。 |
| PUT /api/v1/servers/{id}/ddos | モード：BASELINEまたはADVANCED。QUEUEDまたはUNCHANGEDとquoteRequiredを返します。 |
| PUT /api/v1/network/{id}/rdns | ptr、またはクリアするための空の値。保存されたPTR値を返します。 |
再試行を意図的に行う
注文、出金、サーバーアクション、DDoSリクエストにはIdempotency-Keyが必要です。8～100の英字、数字、ハイフン、アンダースコアを使用し、意図する操作ごとに新しいキーを割り当ててください。不確かな応答を調査できるように、送信前に元のキー、リソース、ペイロードを保存してください。
注文は同じキーと正規化されたリクエストに対して既存の結果を再生できます。注文詳細が変更されると競合が発生します。サーバーアクションの再生は、互換性がある場合に既存のアクションを返します。アカウント内のすべてのサーバーでアクションキーを一意に保ってください。出金は、元のリクエストを成功として返すのではなく、すでに記録されている場合は競合を報告します。
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}受け入れと完了を区別する
202 QUEUED 応答は、ハードウェアリクエストが記録されたことを確認するものです。動作する KVM URL、交換用の root パスワード、マシンが再起動した証拠は含まれません。同様に、ACCEPTED は注文がプロビジョニングに入ったことを記録し、PENDING_REVIEW はオペレーターの確認待ちの出金を記録します。実行について問い合わせる際は、返された識別子を保持してください。
このバージョンにはアクションステータスのポーリングルートはありません。関連する場合はサーバーまたはネットワークデータを再読み込みし、物理的な影響についてはオペレーターの確認を得てください。保存された PTR や DDoS 設定だけでは、公開 DNS やライブネットワーク保護の測定にはなりません。
作業を重複させずに障害に対応する
- 400 検証エラー：再送信前に記載されたフィールドを修正してください。
- 401または403：再試行する前にセッション認証またはCSRF検証を修復してください。
- 404: リソース識別子がサインインしたアカウントに属していることを確認してください。
- 409: エラーコードを確認してください。残高不足、容量枯渇、冪等性の競合には異なる対応が必要です。
- 入金時の502または503：使用可能な新しいアドレスが返されませんでした。転送を開始しないでください。
- タイムアウトまたは読み取り不能な応答：利用可能なアカウント記録を確認し、元のリクエスト詳細を保持してください。新しい操作キーを盲目的に作成しないでください。