可靠且易於理解的API從構建接口的明確規則開始。我們遵循REST最佳實踐,以確保每個開發人員都知道會發生什麼：URL結構是合乎邏輯的,方法對應於操作,錯誤易於解釋。
這降低了登錄閾值，簡化了集成，並允許在沒有混亂的情況下擴展系統。
URL和HTTP方法約定
| 方法 | 指定 | 查詢示例 |
|---|---|---|
| `GET` | 獲取資源 | `GET /users/42` |
| `POST` | 創建新資源 | `POST /users` |
| `PUT` | 完全更新資源 | `PUT /users/42` |
| `PATCH` | 部分資源更新（opz.）`PATCH /users/42` | |
| `DELETE` | 刪除資源 | `DELETE /users/42` |
使用復數形式的名詞（「/users」，「/devices」，「/games」）
嵌套實體被描述為層次結構（'/users/42/sessions'）
所有查詢均通過HTTPS進行
錯誤處理標準
| 代碼 | 值為 | 示例消息 |
|---|---|---|
| `400` | 不正確的請求 | `Missing required field: email` |
| `401` | 未授權 | `Invalid token or expired session` |
| `403` | 禁止訪問 | `Access denied to resource` |
| `404` | 未找到 | `User with ID 42 not found` |
| `409` | 沖突（例如重復） | `Email already in use` |
| `422` | 驗證錯誤 | `Field 'age' must be a number` |
| `500` | 內部服務器錯誤 | `Unexpected exception, contact support` |
錯誤響應結構：
json
{
"error": {
"code": 400, "message": "Missing required field: email", "details": {...}
}
}對開發人員的好處
快速理解API邏輯而無需多余的文檔
所有模塊和實體的統一方法
通過標準代碼和格式輕松調試和編寫
與OpenAPI/Swagger、Postman、SDK自動生成兼容
簡化支持、測試和CI/CD
在哪裏，特別重要
開放或合作夥伴API平臺
具有多個開發團隊的項目
微服務體系結構或API第一方法
具有大量實體和交互的系統