API の使い方

ASHIKA Network の API を使うと、お客様パネルでできることの一部を、プログラムから行えます。サーバーの起動・停止・再起動、コンソールへのコマンド送信、ファイルの読み書きができます。

#はじめの一歩

1. APIキーを発行する

   お客様パネルの 「API」 で、名前を付けてキーを発行します。表示されたキー（ashk_ で始まる文字列）を控えてください。もう一度見ることはできません。

2. サーバーの一覧を取ってみる

   キーを Authorization ヘッダに入れて、サーバーの一覧を取ります。

   bashコピー

   curl https://api.ashikanw.com/v1/servers \
     -H "Authorization: Bearer ashk_ここにキー"

   自分のサーバーの一覧が JSON で返ってくれば成功です。

3. 操作してみる

   一覧の id（8 文字）を使って、サーバーを再起動してみます。

   bashコピー

   curl -X POST https://api.ashikanw.com/v1/servers/1a2bc34d/power \
     -H "Authorization: Bearer ashk_ここにキー" \
     -H "Content-Type: application/json" \
     -d '{"signal": "restart"}'

できることの全部は API リファレンス に、よくある使い方は 使い方の例 にあります。

#URL

どのエンドポイントも、頭は次の URL です。通信は HTTPS だけです。

https://api.ashikanw.com/v1

お客様パネルの https://dash.ashikanw.com/api/v1 も、まったく同じものです。

#認証

すべてのリクエストに、APIキーを次の形で付けます。

Authorization: Bearer ashk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 触れるのは、キーを発行したアカウントのサーバーだけです。他の人のサーバーの ID を指定しても「見つかりません」になります。
• キーはアカウントのパスワードと同じくらい大切です。プログラムに直接書かず、環境変数や GitHub の Secrets などに入れてください。
• キーが漏れたかもしれないときは、パネルの「API」ですぐに消してください。消したキーはその場で使えなくなります。

#サーバーの指定

URL の {id} には、サーバーの 8 文字の ID（例: 1a2bc34d）を入れます。パネルのサーバーの URL（dash.ashikanw.com/servers/…）や、サーバー一覧の API の id で分かります。UUID でも指定できます。

#応答の形

うまくいったときは、HTTP の状態が 200 で、中身が data に入って返ります。

{
  "data": {
    "id": "1a2bc34d",
    "name": "my-bot",
    "status": "RUNNING"
  }
}

ファイルの中身（テキストを読む・ダウンロード）だけは、JSON ではなく中身そのものが返ります。

#エラー

うまくいかなかったときは、HTTP の状態が 400 番台か 500 番台で、error に理由が入って返ります。code はプログラムで見分けるための英語の名前、message は人が読むための説明です。

{
  "error": {
    "code": "not_running",
    "message": "サーバーが起動していません。"
  }
}

#回数の制限

1 つのキーにつき、1 分間に 120 回まで受け付けます。応答のヘッダで、残りの回数が分かります。

状態を見張るときは、数秒〜数十秒おきに取れば十分です。

#操作の記録

API で行った操作（起動・停止、コマンド、ファイルの書き込み・名前の変更・削除）は、パネルのサーバーの「アクティビティ」に残ります。覚えのない操作があれば、キーを消して作り直してください。

#できないこと

今の API では、サーバーの購入・延長・削除、プランの変更、残高のチャージはできません。お金や消えると困るものに関わる操作は、お客様パネルから行ってください。ほしい機能があれば Discord で教えてください。