一、接口概述

本接口文檔用于描述圖書管理系統中的一系列 Restful 接口，涵蓋圖書的查詢、添加、更新與刪除操作，以及用戶的登錄注冊等功能，方便客戶端與服務器之間進行數據交互。

二、接口基礎信息

• 接口地址：https://book-management-api.example.com/api

• 請求方式：支持 GET、POST、PUT、DELETE

• 請求數據格式：JSON

• 響應數據格式：JSON

三、接口詳情

（一）用戶注冊接口

• 接口名稱：/users/register

• 接口描述：新用戶注冊賬號，提交用戶名、密碼、郵箱等信息創建新用戶記錄。

• 請求方式：POST

• 請求參數：

{"username": "string","password": "string","email": "string"
}

• 響應狀態碼及說明

  • 201 Created：用戶注冊成功，響應示例：

{"message": "用戶注冊成功","user_id": 123
}

• 400 Bad Request：請求數據格式錯誤或用戶名已存在等情況，示例：

{"error": "用戶名已存在，請更換用戶名"
}

（二）用戶登錄接口

• 接口名稱：/users/login

• 接口描述：用戶提交用戶名和密碼進行登錄驗證，成功后返回認證令牌。

• 請求方式：POST

• 請求參數：

{"username": "string","password": "string"
}

• 響應狀態碼及說明

  • 200 OK：登錄成功，返回令牌，示例：

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

• 401 Unauthorized：用戶名或密碼錯誤，示例：

{"error": "用戶名或密碼錯誤"
}

（三）獲取所有圖書接口

• 接口名稱：/books

• 接口描述：獲取圖書管理系統中所有圖書的信息列表。

• 請求方式：GET

• 請求參數：無

• 響應狀態碼及說明

  • 200 OK：成功獲取圖書列表，響應示例：

[{"book_id": 1,"title": "百年孤獨","author": "加西亞·馬爾克斯","publication_year": 1967,"isbn": "9787544253994"},{"book_id": 2,"title": "平凡的世界","author": "路遙","publication_year": 1986,"isbn": "9787530212004"}
]

（四）獲取單本圖書接口

• 接口名稱：/books/{book_id}

• 接口描述：根據圖書 ID 獲取特定圖書的詳細信息。

• 請求方式：GET

• 請求參數

  • book_id：路徑參數，整數類型，必填，指定要查詢的圖書 ID。

• 響應狀態碼及說明

  • 200 OK：成功獲取圖書信息，響應示例：

{"book_id": 1,"title": "百年孤獨","author": "加西亞·馬爾克斯","publication_year": 1967,"isbn": "9787544253994"
}

• 404 Not Found：未找到指定 ID 的圖書，示例：

{"error": "未找到指定圖書"
}

（五）添加圖書接口

• 接口名稱：/books

• 接口描述：添加一本新圖書到圖書管理系統，需提供圖書的相關信息。

• 請求方式：POST

• 請求參數：

{"title": "string","author": "string","publication_year": "number","isbn": "string"
}

• 響應狀態碼及說明

  • 201 Created：圖書添加成功，響應示例：

{"message": "圖書添加成功","book_id": 3
}

• 400 Bad Request：請求數據格式錯誤或缺少必填項，示例：

{"error": "缺少必填項：publication_year"
}

（六）更新圖書接口

• 接口名稱：/books/{book_id}

• 接口描述：根據圖書 ID 更新特定圖書的信息，可部分更新。

• 請求方式：PUT

• 請求參數

  • book_id：路徑參數，整數類型，必填，指定要更新的圖書 ID。

  • 請求體：包含要更新的圖書信息，示例：

{"title": "百年孤獨（新版）","publication_year": "2018"
}

• 響應狀態碼及說明

  • 200 OK：圖書信息更新成功，響應示例：

{"message": "圖書信息更新成功"
}

• 404 Not Found：未找到指定 ID 的圖書，示例：

{"error": "未找到指定圖書"
}

• 400 Bad Request：請求數據格式錯誤或更新數據與數據庫約束沖突等情況，示例：

{"error": "更新數據不符合數據庫約束"
}

（七）刪除圖書接口

• 接口名稱：/books/{book_id}

• 接口描述：根據圖書 ID 刪除特定圖書記錄。

• 請求方式：DELETE

• 請求參數

  • book_id：路徑參數，整數類型，必填，指定要刪除的圖書 ID。

• 響應狀態碼及說明

  • 204 No Content：圖書刪除成功，無響應體內容。

  • 404 Not Found：未找到指定 ID 的圖書，示例：

{"error": "未找到指定圖書"
}

四、接口安全

• 認證方式：基于 Token 的認證方式。客戶端在每次請求時，需在請求頭中添加 Authorization 字段，格式為 Bearer <token>。

• 權限控制：普通用戶僅能查詢圖書信息；管理員用戶具有添加、更新、刪除圖書以及管理用戶賬號的權限。

五、錯誤處理

• 除上述接口特定錯誤情況外，對于其他網絡錯誤、服務器內部錯誤等，統一返回以下狀態碼及說明：

  • 500 Internal Server Error：服務器內部錯誤，示例：

{"error": "服務器內部錯誤，請稍后重試"
}

• 503 Service Unavailable：服務器暫時不可用，示例：

{"error": "服務器暫時不可用，正在維護中"
}

六、版本控制

• 本接口文檔遵循語義化版本控制，當前版本為 v1.0。如有接口更新或修改，將按照語義化版本規則進行版本升級，并及時更新文檔。