顧客パネルで発行する 1 つのトークン
ベアラートークンとして送信されます。必要であれば読み取り専用や単一サービスに限定できます。トークンはパスワードとは独立しており、一つを失効させてもログアウトされることはありません。
一つのトークンで、顧客パネルでできることすべて
HTTPS 経由の JSON。SDK は不要、別途の開発者アカウントも不要、そしてパネルにはあってここにはないエンドポイントもありません。
サーバーを作成
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'ビルド ID を即座に返します。マシンは約 60 秒後に SSH で応答するようになり、認証情報が送信される前にアドレスのルーティングが完了しています。
20 個のエンドポイント
すべてを五つのグループに
ベース URL https://api.vpsoffshore.com/v1。パスでバージョン管理されます。v2 が登場しても v1 は動作を続け、廃止日は 1 年前に告知されます。
サーバー
GET
/servers
アカウント上のすべてのサービスを、状態・プラン・アドレスとともに表示します。
POST
/servers
作成します。ビルド ID とともに即座に応答が返り、約 1 分後にはサーバーへ到達可能になります。
GET
/servers/{id}
直近 1 時間分のリアルタイムなリソース使用状況を含む、単一サービスの情報。
PATCH
/servers/{id}
プランの変更。ディスク容量が許す範囲では、再インストールなしでリサイズできます。
DELETE
/servers/{id}
削除します。ディスクは 14 日間保持された後、再発行の前に消去されます。
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
ストレージ
GET
/servers/{id}/snapshots
1 つのサービスのスナップショットを新しい順に表示。
POST
/servers/{id}/snapshots
スナップショットを取得してください。差分方式のため高速で、ディスク使用量が倍増することもありません。
POST
/snapshots/{id}/restore
同じ場所への復元、または同一以上のプランの別サービスへの復元が可能です。
DELETE
/snapshots/{id}
スナップショットを削除します。
ネットワーク
GET
/servers/{id}/addresses
サービスにルーティングされたアドレス（v4 および v6）。
POST
/servers/{id}/addresses
追加アドレス、または /29 をご申請ください。
PUT
/addresses/{ip}/rdns
逆引き DNS を設定します。次のゾーン更新を待たず、1 分以内に反映されます。
GET
/servers/{id}/bandwidth
転送量カウンターです。参考情報であり—超過を判定する上限はありません。
カタログ
GET
/plans
仕様と価格を含むすべてのプラン。このサイトが表示に使用しているものと同じデータソースです。
GET
/images
アップロードしたものを含め、利用可能なイメージと ISO です。
POST
/images
ISO を URL からアップロードします。コンソールを接続した状態で起動します。
請求
GET
/invoices
支払い済みおよび未払いの請求書を、通貨とチェーン上のトランザクションとともに表示します。
POST
/invoices/{id}/pay
対応する 8 種類の通貨のいずれかで、支払いアドレスを発行します。
GET
/credits
適用された SLA 補償と、それぞれの原因となったインシデント。
顧客パネルでできることはすべてここにあり、ここにあるものは顧客パネルにも欠けていません。両者が食い違う場合はそれは不具合であり、顧客パネルからお知らせください。仕様として文書化するのではなく、修正します。
動作の仕組み
1 時間以内に気づく 4 つの決定
API の評価は、正常系ではなく異常系で決まります。以下の 4 つのうち 3 つは、何か問題が起きたときに何が起こるかについてです。
JSON を送信し JSON を受信、SDK は不要です
独自エンベロープも、XML フォールバックも、署名の儀式もない、素の HTTPS です。curl でできることなら、それがそのままクライアントになります。Go、Python、TypeScript 向けの公式ライブラリもありますが、いずれも必須ではありません。
不用意に到達することのないレート制限
トークンあたり毎分 600 リクエスト、作成系呼び出しは 60 リクエストまでです。すべてのレスポンスには残り上限がヘッダーで示され、超過時は 429 とともに待機秒数が返されます。リクエストが無言で破棄されることはありません。
対処方法を示すエラー
4xx エラーには、機械可読なコード、人間が読める文章、そして問題のあるフィールドが含まれます。当社は、推測を強いる短いエラーよりも、長くても分かりやすいエラーを返すことを選びます。
一度だけ書く 2 つのこと
認証とエラーの内容
最初の失敗の後ではなく、最初の呼び出しを書く前に、両方とも読んでおく価値があります。
認証する
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"トークンはパネルで発行し、読み取り専用や特定のサービスに限定できます。パスワードとは独立しており、1 つを取り消してもどこからもログアウトされません。
レート制限を読む
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41失敗したレスポンスだけでなく、すべてのレスポンスに付与されます。上限を超えると、待機すべき秒数とともに 429 が返されます — 黙って破棄されることも、レスポンスが省略されることもありません。
エラーには対象のフィールドが示されます
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}機械可読なコード、人が読める説明文、そして原因となったフィールドを返します。詳細なエラーは、推測が必要な簡潔なエラーより扱いやすいものです。
ビルドの状態を確認
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statebuilding → running と遷移します。何かを作成する前に登録が必要な webhook はなく、1 秒に一度のポーリングは制限内に収まります。
申請不要
トークンは顧客パネル内にあり、パネルは最初のサーバーに付属します
開発者アカウントも、承認も、本番環境と異なる挙動のサンドボックスもありません。