良い API は、良い意味で地味なものです。予測しやすい URL、正直なエラー、小さく安定したスキーマ、驚きのない動作。 これらは Noxyr Server API の設計を形作っている原則で、Stripe、Resend、OpenAI、公式の Discord API の背後にある業界標準から取り入れています。
1. バージョン付きの URL
すべてのエンドポイントは /api/v1/ の下にあります。破壊的な変更を加える場合は /api/v2/ の下に追加されるため、古い連携もそのまま動き続けます。Discord も /api/v10/ で同じことをしています。API にバージョンがないと、スキーマを変更するたびにサポートへの問い合わせが発生することになります。
2. リソースが先、アクションは後
Noxyr のエンドポイントは名詞で名付けられています。server、tickets、activity、invoices、reviews、giveaways です。すべて読み取り専用で、すべて GET です。書き込み機能を追加する場合も、同じリソースに対する POST/PATCH/DELETE として提供する予定です。これは REST の慣習にきれいに沿っており、頭の中のモデルを小さく保てます。
3. Bearer トークン、秘密は一つ
認証は Authorization: Bearer nxr_... です。署名付きリクエストも、読み取り専用のサーバーデータに対する OAuth フローもありません。最近の開発者向け API がこの形式に収束しているのは、curl、ブラウザ、Postman、サーバーレスのエッジなど、どこでも動くからです。Discord も OAuth で認可されたユーザーに対して bearer トークンを使っており、このパターンは広く使われています。
4. ハッシュだけを保存する
Noxyr のキーはすべて、サーバー側で SHA-256 によりハッシュ化されます。生の値は生成時に一度だけ表示され、それ以降は表示されません。万一データベースが漏えいしても、使えるキーは一つもありません。Stripe、GitHub、Resend など、運用のしっかりした API ベンダーはすべてこの方式を取っています。キーを元に戻せる形で保存していることは危険信号です。
5. 細かいスコープ
一つのキーに、六つの独立したスイッチがあります。レビューは公開データで、売上は非公開です。この二つを分けておけば、レビューだけのキーをマーケティングパートナーに渡しつつ、売上の数字は別のスイッチの後ろに置いておけます。スコープの変更は即座に反映されます（リクエストごとに確認されるため）。そのため、取り消しにキーのローテーションは不要です。
6. 正直なエラーレスポンス
すべてのエラーは、安定した機械可読のコードと人間向けのメッセージを含む JSON です:
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }機械可読のコードがあると、リトライやダッシュボードの実装が簡単になります。人間向けのメッセージがあると、デバッグが速く進みます。2026 年 7 月に "discord increased api errors" という検索が急増したこと（Google トレンドでの「急上昇」）は、エラーが不明瞭だとユーザーが推測に頼ることになる様子を示しています。
7. 時系列のゼロ埋め
/api/v1/activity エンドポイントは、件数がゼロの日も含めて、要求された期間のすべての日を返します。フロントエンドで隙間を埋める必要がなく、グラフが不規則な日付の間で飛ぶこともありません。小さな工夫ですが、使い勝手への効果は大きいです。
8. ヘッダーによるレート制限
すべてのレスポンスには RateLimit-* ヘッダーが付いているため、クライアントは 429 に達する前に待機できます。これは標準化された IETF ドラフトの形式で、GitHub など他の現代的な API と同じ形です。そのため、この形式に対応している既存のクライアントライブラリであればそのまま動きます。
9. 読み取り専用データには緩やかな CORS
読み取り専用のエンドポイントは Access-Control-Allow-Origin: * を返します。認証を行うのはオリジンではなくキーなので、CORS を開放してもセキュリティ上のコストはかかりません。また、ブラウザのツールから API を直接呼び出せるため、プロキシの仕組みや localhost の回避策は不要です。
10. 小さく安定したスキーマ
すべてのレスポンスは一画面に収まります。任意のネストされたオブジェクトはなく、機能フラグがオンのときだけ現れるフィールドもありません。小さいスキーマはキャッシュしやすく、テストもしやすく、TypeScript の型も書きやすいです。
実際の例は Server API チュートリアル をご覧ください。Discord 自体に不具合があるときは、それらの Discord API エラーが実際に何を意味するのかをご覧ください。