Library system api

--- tags: api文件 --- # Library system api ![](https://i.imgur.com/qET2Fb7.png) > 圖書館管理系統，使用 Laravel 做出管理書籍以及使用者借書還書的 api。 > 使用者分為 3 級，管理員、一般會員、高級會員。只有管理員可以新增會員，也可以幫會員借書還書。 > 根據會員等級不同，可借的書籍量也會不同，書籍有分為新書以及舊書，新書會特別規定只能借閱 5 天。 ## 登入並取得 token ### Request - **URI：127.0.0.1:8000/api/user/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |POST |/login | 登入並取得token | - **Header** ``` json= { "Content-Type" : "application/json" } ``` - **Body** ``` json= { "username" : "admin", "password" : "****" } ``` ### Response - **Header** * **status code 200** ``` json= { "userToken" : "******" } ``` - **Body** - **status code 200** ```json= { "message": "login successfully" } ``` - **status code 400** ```json= { "message": "bad request", "reason": "Username or password false" } ``` ## 創立使用者帳號（管理者權限） ### Request - **URI：127.0.0.1:8000/api/user/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |POST | N/A | 創立帳號（需要管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** 輸入帳密以及使用者等級 ``` json= { "username" : "gill", "password" : "00000000", "Lv":"2" } ``` ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "create successfully" } ``` - **status code 400** <details> <summary>輸入帳密格式錯誤 Lv要1-3 帳號 3-16位元密碼8-20位元數字及英文組成</summary> ```json= { "message": "bad request", "reason": { "Lv": [ "Lv should between 1 to 3" ], "username": [ "username between 3 to 16 charactersand only 0-9,a-z,A-Z" ], "password": [ "password should between 8 to 20 characters and only 0-9,a-z,A-Z " ] } } ``` </details> <details> <summary>帳號名稱已存在</summary> ```json= { "message": "bad request", "reason": "this name already used" } ``` </details> - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 列出所有使用者管理者可以看到所有使用者資料，使用者只能看到自己的資料 ### Request - **URI：127.0.0.1:8000/api/user/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |GET | N/A | 列出使用者 | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** N/A ### Response - **Header** N/A - **Body** - **status code 200** 成功範例： ```json= [ { "id": 1, "name": "admin", "Lv": 3, "created_at": null, "updated_at": "2020-07-30T02:33:43.000000Z" }, { "id": 3, "name": "gill", "Lv": 1, "created_at": "2020-07-22T01:56:02.000000Z", "updated_at": "2020-07-29T07:18:23.000000Z" }, ] ``` - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 列出單一使用者（管理者權限） ### Request - **URI：127.0.0.1:8000/api/user/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |GET | {UserId} | 列出單一使用者（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** N/A ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "id": 3, "name": "gill", "Lv": 1, "created_at": "2020-07-22T01:56:02.000000Z", "updated_at": "2020-07-29T07:18:23.000000Z" } ``` - **status code 400** ```json= { "message": "bad request", "reason": "User id ls false" } ``` - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 更新使用者資料（管理者權限） ### Request - **URI：127.0.0.1:8000/api/user/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |PUT | {UserId} | 更新使用者資料（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** 範例：依更改需求輸入帳號密碼以及Lv（個別輸入也可以） ```json= { "username" : "joey", "password" : "00000000", "Lv":"2" } ``` ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "update successfully" } ``` - **status code 400** <details> <summary>輸入帳密格式錯誤 Lv要1-3 帳號 3-16位元密碼8-20位元數字及英文組成</summary> ```json= { "message": "bad request", "reason": { "Lv": [ "Lv should between 1 to 3" ], "username": [ "username between 3 to 16 charactersand only 0-9,a-z,A-Z" ], "password": [ "password should between 8 to 20 characters and only 0-9,a-z,A-Z " ] } } ``` </details> <details> <summary>帳號名稱已存在</summary> ```json= { "message": "bad request", "reason": "this name already used" } ``` </details> - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 刪除使用者資料（管理者權限） ### Request - **URI：127.0.0.1:8000/api/user/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |DELETE | {UserId} | 刪除使用者資料（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** N/A ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "update successfully" } ``` - **status code 400** ```json= { "message": "bad request", "reason": "User id ls false" } ``` - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 列出借書紀錄 1.管理者可以看到所有紀錄，使用者只能看到自己的紀錄 2.借書紀錄會依照時間排序 3.give back =1 已歸還，give back =0 未歸還 ### Request - **URI：127.0.0.1:8000/api/BorrowLog/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |GET | N/A | 列出所有借書紀錄（管理者權限） | |GET | book/{BookId} | 列出書的借書紀錄（管理者權限） | |GET | user/{UserId} | 列出使用者的借書紀錄（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** N/A ### Response - **Header** N/A - **Body** 借書紀錄會依照時間排序 give back =1 已歸還，=0 未歸還 - **status code 200** <details> <summary>列出所有紀錄</summary> ```json= { "14": { "id": 17, "user_id": 1, "bookname": "book", "borrow_time": "2020-07-29 16:54:23", "give_back_time": null, "give_back": 0, "book_id": 2 }, "13": { "id": 16, "user_id": 3, "bookname": "Book", "borrow_time": "2020-07-28 15:46:29", "give_back_time": "2020-07-29 16:47:34", "give_back": 1, "book_id": 2 }, "12": { "id": 15, "user_id": 1, "bookname": "Book", "borrow_time": "2020-07-28 14:34:56", "give_back_time": "2020-07-28 14:36:08", "give_back": 1, "book_id": 2 } } ``` </details> <details> <summary>使用者紀錄</summary> ```json= { "id": 1, "name": "admin", "Lv": 3, "created_at": null, "updated_at": "2020-07-31T02:59:24.000000Z", "borrow_log": [ { "id": 3, "user_id": 1, "bookname": "firstBook", "borrow_time": "2020-07-24 10:25:58", "give_back_time": "2020-07-28 14:35:55", "give_back": 1, "book_id": null }, { "id": 15, "user_id": 1, "bookname": "Book", "borrow_time": "2020-07-28 14:34:56", "give_back_time": "2020-07-28 14:36:08", "give_back": 1, "book_id": 2 }, ] } ``` </details> <details> <summary>列出書籍紀錄</summary> ```json= { "id": 2, "bookname": "book", "Borrower": null, "status": 1, "created_at": "2020-07-22T00:55:00.000000Z", "updated_at": "2020-07-30T09:03:23.000000Z", "borrow_log": [ { "id": 15, "user_id": 1, "bookname": "Book", "borrow_time": "2020-07-28 14:34:56", "give_back_time": "2020-07-28 14:36:08", "give_back": 1, "book_id": 2 }, { "id": 16, "user_id": 3, "bookname": "Book", "borrow_time": "2020-07-28 15:46:29", "give_back_time": "2020-07-29 16:47:34", "give_back": 1, "book_id": 2 }, ] } ``` </details> - **status code 400** <details> <summary>User id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "User id ls false" } ``` </details> <details> <summary>Book id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "Book id ls false" } ``` </details> - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 借書 1. 管理者可以幫忙使用者借書還書 2. 一般使用者最多借3本一週，高級使用者最多借5本兩週，新書最多借五天（新增的書籍一個月內為新書） ### Request - **URI：127.0.0.1:8000/api/borrow/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |POST | N/A | 借書 | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** - 一般借書，輸入書本id ``` json= { "BookId" : "**" } ``` - 管理者幫使用者借書，輸入使用者id以及書本id ``` json= { "BookId" : "**" "UserId" : "**" } ``` ### Response - **Header** N/A - **Body** - **status code 200** ``` json= { "message": "borrow successfully" } ``` - **status code 400** <details> <summary>User Id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "User id ls false" } ``` </details> <details> <summary>Book id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "Book id ls false" } ``` </details> <details> <summary>書已被借走</summary> ```json= { "message": "bad request", "reason": "book not found or already borrowed" } ``` </details> <details> <summary>使用者有書超過期限未還</summary> ```json= { "message": "bad request", "reason": "you have same book not give back over time" } ``` </details> <details> <summary>一般使用者最多同時借三本書</summary> ```json= { "message": "bad request", "reason": "only borrow 3 books" } ``` </details> <details> <summary>高級使用者最多同時借五本書</summary> ```json= { "message": "bad request", "reason": "only borrow 5 books" } ``` </details> - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 還書管理者可以幫忙使用者借書還書 ### Request - **URI：127.0.0.1:8000/api/returnBook/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |PUT | N/A | 還書 | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** - 一般借書，輸入書本id ``` json= { "BookId" : "**" } ``` - 管理者幫使用者借書，輸入使用者id以及書本id ``` json= { "BookId" : "**" "UserId" : "**" } ``` ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "give back successfully" } ``` - **status code 400** <details> <summary>User Id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "User id ls false" } ``` </details> <details> <summary>Book id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "Book id ls false" } ``` </details> - **status code 401** <details> <summary>token 輸入錯誤</summary> ```json= { "message": "Unauthorized", "reason": "token false" } ``` </details> <details> <summary>token 過期（有效期限為一天）</summary> ```json= { "message": "Unauthorized", "reason": "token out time" } ``` </details> ## 書籍目錄 ### Request - **URI：127.0.0.1:8000/api/library/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |GET | N/A | 還書 | |GET | {BookId} | 還書 | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** N/A ### Response - **Header** N/A - **Body** - **status code 200** status = 1 書還在，status = 0 書已經被借走了 ```json= [ { "id": 2, "bookname": "book", "Borrower": null, "status": 1, "created_at": "2020-07-22T00:55:00.000000Z", "updated_at": "2020-07-30T09:03:23.000000Z" }, { "id": 3, "bookname": "book2", "Borrower": null, "status": 1, "created_at": "2020-07-27T09:22:55.000000Z", "updated_at": "2020-07-30T08:52:55.000000Z" } ] ``` - **status code 400** <details> <summary>User Id 輸入錯誤</summary> ```json= { "message": "bad request", "reason": "User id ls false" } ``` </details> ## 新增書籍（管理者權限） ### Request - **URI：127.0.0.1:8000/api/library/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |POST | N/A | 新增書籍（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** ```json= { "bookname" : "book name" } ``` ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "create successfully" } ``` - **status code 400** <details> <summary>書名不能為空值，不能超過20字元</summary> ```json= { "message": "bad request", "reason": "bookname can not null and can not over 20 characters." } ``` </details> ## 更新書籍（管理者權限） ### Request - **URI：127.0.0.1:8000/api/library/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |POST | {BookId} | 新增書籍（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** ```json= { "bookname" :"linux" } ``` ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "update successfully" } ``` - **status code 400** <details> <summary>書名不能為空值，不能超過20字元</summary> ```json= { "message": "bad request", "reason": "bookname can not null and can not over 20 characters." } ``` </details> <details> <summary>Book id 錯誤</summary> ```json= { "message": "bad request", "reason": "book id ls false" } ``` </details> ## 刪除書籍（管理者權限） ### Request - **URI：127.0.0.1:8000/api/library/endpoint** |method | endpoint | 說明 | |--- | --- | ---| |DELETE | {BookId} | 新增書籍（管理者權限） | - **Header** ``` json= { "Content-Type" : "application/json", "userToken" : "*********" } ``` - **Body** N/A ### Response - **Header** N/A - **Body** - **status code 200** ```json= { "message": "delete successfully" } ``` - **status code 400** <details> <summary>Book id 錯誤</summary> ```json= { "message": "bad request", "reason": "book id ls false" } ``` </details>