信頼できる直感的なAPIは、インターフェイスを構築するための明確なルールから始まります。URL構造は論理的であり、メソッドはアクションに適しており、エラーは簡単に解釈されます。
これにより、入力しきい値が下がり、統合が簡素化され、システムがカオスなしで拡張できるようになります。
URLとHTTPメソッドの表記法
| メソッド | アポイントメント | サンプルクエリ |
|---|---|---|
| 「GET」 | リソースの取得 | 'GET/users/42' |
| 「POST」 | 新しいリソースを作成する | 'POST/users' |
| 「PUTA」 | リソースの完全な更新 | 'PUT/users/42' |
| 「PATCH」 | 部分的なリソース更新（Opt） 'PATCH/users/42' | |
| 「DELETE」 | リソースを削除する | 'DELETE/users/42' |
複数の名詞が使用されます（'/users'、'/devices'、 '/games'）
ネストされたエンティティは階層として記述されます（'/users/42/sessions'）
すべてのリクエストはHTTPS経由で実行されます
エラー処理規格
| Code（コード） | Value（価値 | サンプルメッセージ |
|---|---|---|
| `400` | 無効なリクエスト | '必須フィールドがありません：email' |
| `401` | 承認されていません | '無効なトークンまたは期限切れのセッション' |
| `403` | アクセスが拒否されました | 'リソースへのアクセス拒否' |
| `404` | 見つかりませんでした | 'ID 42のユーザーが見つかりません' |
| `409` | 競合（例：重複） | '既に使用中のメール' |
| `422` | バリデーションエラー | 'フィールド'の年齢'は数値でなければならない' |
| `500` | 内部サーバーエラー | '予期しない例外、連絡先サポート' |
エラー応答構造：
json
{
"error": {
"code": 400, "message": "Missing required field: email", "details": {...}
}
}開発者の利点
不要なドキュメントなしでAPIロジックをすばやく理解
すべてのモジュールとエンティティに対する統一されたアプローチ
標準コードとフォーマットによる簡単なデバッグとロギング
OpenAPI/Swagger、 Postman、 SDK自動生成との互換性
サポート、テスト、CI/CDの簡素化
特に重要な点
オープンまたはパートナーのAPIプラットフォーム
複数の開発チームによるプロジェクト
マイクロサービス・アーキテクチャまたはAPIファースト・アプローチ
多くのエンティティとインタラクションを持つシステム