Fukeiin 日本風景印

# Fukeiin 日本風景印 # 規劃第一版 RESTful API 文件 ## API目錄： |流水號| 功能 | URL | Method | | --| -------- | -------- | -------- | |1| 登入 | /api/login | post| |2| 註冊 | /api/regist | post| |3| 登出 | /api/logout | post| |4| 首頁-6個熱門城市 | /api/index/hot_cities | get| |5| 首頁-6個最新遊記 | /api/index/latest_posts | get| |6| 城市列表 | /api/cities/ | get| |10| 鄉鎮列表 | /api/cities/{city_id}/towns | get| |14| 郵局列表 | /api/towns/{town_id}/locations | get| |18| user遊記詳情 | /api/posts/{post_id} | get| |19| user修改遊記詳情 | /api/posts/{post_id} | put| |20| user刪除遊記詳情 | /api/posts/{post_id} | delete| |21| 該郵局玩家遊記詳情列表 | /api/locations/{location_id}/posts | get| |22| 郵局詳情(目前使用的風景印圖片_地址_局名) | /api/locations/{location_id}/location_introduce | get| |23| 郵局詳情(歷代風景印列表) | /api/locations/{location_id}/history_postmark_list | get| |24| 郵局歷代風景印詳情 | /api/postmarks/{postmark_id} | get| |28| user新增風景印+遊記 | /api/postmark | post| |29| 收藏/解除收藏user的遊記 | /api/collections/posts | put| |30| user收藏列表-城市列表 | /api/collections/cities | get| |31| user收藏列表-郵局列表 | /api/collections/locations | get| |32| user收藏列表-該郵局下所有遊記 | /api/collections/locations/{location_id}/posts | get| |35| user所有有收藏的遊記(收藏獨立拉出來做) | /api/collections/posts |get| |33| user個人頁 | /api/profile/{user_id} | get| |34| 修改user個人頁 | /api/profile | put| # API詳細操作手冊： ## 會員註冊 [POST] [api/regist] | 功能 | URL | Method | | -------- | -------- | -------- | | 註冊 | /api/regist | post| #### Request ##### Headers ``` Accept:application/x-www-form-urlencoded ``` ##### Body |欄位名稱 | 資料型態 |備註| | -------- | -------- | -------- | |account|string|unique, email formate| | password | string || | rePassword | string || | name | string || 範例格式 ``` { account: "test@gmail.com", password: "password", rePassword: "rePassword", name: "test" } ``` **Response** #### 成功 201 ```{} { "status": "regist successfuly", "result": { "message": "regist successfuly", "datas": [ { "id": 3, "account": "test@gmail.com", "password": "123", "name": "test", "create_time": "2020-06-29 01:33:30", "update_time": "2020-06-29 01:33:30" } ] } } ``` #### 失敗 422 ```{} { "status": "regist failed", "result": { "message": "please fill account or password", "datas": [] } } ``` #### 失敗 422 ```{} { "status": "regist failed", "result": { "message": "please fill name", "datas": [] } } ``` #### 失敗 422 ```{} { "status": "regist failed", "result": { "message": "enter the password differently", "datas": [] } } ``` #### 失敗 422 ```{} { "status": "regist failed", "result": { "message": "account formate incorrectly, should be email formate", "datas": [] } } ``` #### 失敗 422 ```{} { "status": "regist failed", "result": { "message": "this account has been registed", "datas": [] } } ``` ## 會員登入 [POST] [api/login] | 功能 | URL | Method | | -------- | -------- | -------- | | 登入 | /api/login | post| #### Request ##### Headers ``` Accept:application/x-www-form-urlencoded ``` ##### Body |欄位名稱 | 資料型態 |備註| | -------- | -------- | -------- | | account | string |email-formate, unique| | password | string || 範例格式 ``` { account: "test2@gmail.com", password: "password" } ``` #### Response #### 成功 201 ```{} { "status": "login successfully", "result": { "message": "login successfully", "datas": [ { "id": 10, "account": "test2@gmail.com", "api_token": "U8vIZDFTVGdiswWGKg7v", "name": "test2", "head_img": "/images/upload/img_test.png" } ] } } ``` #### 失敗 422 ```{ { "status": "login failed", "result": { "message": "please fill up account or password", "datas": [] } } ``` #### 失敗 401 ```{ { "status": "login failed", "result": { "message": "account or password incorrected", "datas": [] } } ``` ## 登出 [POST] [api/logout] | 功能 | URL | Method | | -------- | -------- | -------- | | 登出 | /api/logout | post| #### Request ##### Headers ``` Accept: application/json apitoken: 使用者的apitoken ``` #### Response #### 成功 200 ```{} { "status": "logout successfully", "result": { "message": "logout successfully", "datas": [ { "id": 10, "account": "test2@gmail.com", "name": "test2", "head_img": "/images/upload/img_test.png" } ] } } ``` ## 首頁-6個熱門城市 [GET] [/api/index/hot_cities] | 功能 | URL | Method | | -------- | -------- | -------- | | 首頁-6個熱門城市 | /api/index/hot_cities | get| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get hot cities successfully", "result": { "message": "get hot cities successfully", "datas": [ { "id": 1, "name": "大阪府", "city_img": "/images/upload/img_大阪府.png" }, { "id": 2, "name": "北海道", "city_img": "/images/upload/img_北海道.png" }, { "id": 3, "name": "沖繩縣", "city_img": "/images/upload/img_沖繩縣.png" }, { "id": 4, "name": "京都府", "city_img": "/images/upload/img_京都府.png" }, { "id": 5, "name": "東京都", "city_img": "/images/upload/img_東京都.png" }, { "id": 6, "name": "福岡縣", "city_img": "/images/upload/img_福岡縣.png" } ] } } ``` ## 首頁-6個最新遊記 [GET] [/api/index/latest_posts] | 功能 | URL | Method | | -------- | -------- | -------- | | 首頁-6個最新遊記 | /api/index/latest_posts | get| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{ { "status": "get latest 9 posts successfully", "result": { "message": "get latest 9 posts successfully", "datas": [ { "id": 1, "create_time": "2020-06-17 08:50:08", "user_postmarks": [ { "postmark_img": "/images/upload/img_test.png", "imprint_date": "2020/6/12" } ], "city": { "name": "大阪府" }, "location": { "name": "Zen location" } } ] } } ``` ## 城市列表 [GET] [/api/cities/] | 功能 | URL | Method | | -------- | -------- | -------- | | 城市列表 | /api/cities/ | get| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get all cities successfuly", "result": { "message": "get all cities successfuly", "datas": [ { "id": 1, "name": "北部", "cities": [ { "id": 1, "name": "大阪府" }, { "id": 2, "name": "北海道" }, { "id": 3, "name": "沖繩縣" }, { "id": 4, "name": "京都府" } ] } ] } } ``` ## 鄉鎮列表 [GET] [/api/cities/{city_id/towns/}] | 功能 | URL | Method | | -------- | -------- | -------- | | 鄉鎮列表 | /api/cities/{city_id/towns/} | get| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get all towns successfully", "result": { "message": "get all towns successfully", "datas": [ { "id": 2, "name": "北海道", "towns": [ { "id": 3, "name": "松山區" } ] } ] } } ``` ## 郵局列表 [GET] [/api/towns/{town_id}/locations] | 功能 | URL | Method | | -------- | -------- | -------- | | 郵局列表 | /api/towns/{town_id}/locations | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get all locations successfully", "result": { "message": "get all locations successfully", "datas": [ { "id": 1, "name": "大安區", "locations": [ { "id": 1, "name": "Zen location", "location_postmarks": [ { "id": 1, "postmark_img": "/images/upload/goodidea.png" } ] } ] } ] } } ``` #### 失敗 422 ```{} { "status": "get all locations failed", "result": { "message": "please enter the correct town id", "datas": [] } } ``` ## user遊記詳情 [GET] [/api/post/{post_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | user遊記詳情 | /api/post/{post_id} | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 201 ```{} { "status": "get post successfully", "result": { "message": "get post successfully", "datas": [ { "id": 7, "content": "ggg", "location_id": 1, "user_postmarks": [ { "id": 7, "postmark_img": "/images/upload/img_test.png", "imprint_date": "2020/6/14" } ], "user": { "id": 1, "name": "username" }, "location": { "id": 1, "name": "Zen location", "address": "Zen address" } } ] } } ``` #### 失敗 422 ```{} { "status": "get post failed", "result": { "message": "this post id does not exist", "datas": [] } } ``` ## user修改遊記詳情 [PUT] [/api/post/{post_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | user修改遊記詳情 | /api/post/{post_id} | PUT| #### Request ##### Headers ``` Accept:application/x-www-form-urlencoded apitoken: 使用者的apitoken ``` ##### Body |欄位名稱 | 資料型態 |備註| | -------- | -------- | -------- | |locationID|int|| | imprintDate | string || |content|string|| 範例格式 ``` locationID: 1 content: test_content imprintDate: 2020/6/66 ``` #### Response #### 成功 201 ```{ { "status": "update post successfully", "result": { "message": "update post successfully", "datas": [ { "content": "content", "location_id": "1", "imprintDate": "2020/6/66" } ] } } ``` #### 失敗 422 ```{} { "status": "validate post failed", "result": { "message": "this post id does not exsit", "datas": [] } } ``` ## user刪除遊記詳情 [DELETE] [/api/post/{post_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | user刪除遊記詳情 | /api/post/{post_id} | DELETE| #### Request ##### Headers ``` Accept: application/json apitoken: 使用者的apitoken ``` #### Response #### 成功 204 ```{} { "status": "delete post successfully", "result": { "message": "one post has been deleted", "datas": [{"post_id": 10}] } } ``` #### 失敗 403 ```{} { "status": "delete post failed", "result": { "message": "the api token is incorrectly", "datas": [] } } ``` #### 失敗 422 ```{} { "status": "validate post failed", "result": { "message": "this post id does not exsit", "datas": [] } } ``` ## 該郵局玩家遊記詳情列表 [GET] [/api/locations/{location_id}/posts] | 功能 | URL | Method | | -------- | -------- | -------- | | 該郵局玩家遊記詳情列表 | /api/locations/{location_id}/posts | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get posts from location successfully", "result": { "message": "get posts from location successfully", "datas": [ { "id": 1, "posts": [ { "id": 7, "content": "content1", "user_postmarks": [ { "id": 7, "postmark_img": "/images/upload/img_test.png", "imprint_date": "2020/6/66" } ] } ] } ] } } ``` #### 失敗 422 ```{} { "status": "get posts from location failed", "result": { "message": "this location id does not exist", "datas": [] } } ``` ## 郵局詳情(目前使用的風景印圖片_地址_局名) [GET] [/api/locations/{location_id}/location_introduce] | 功能 | URL | Method | | -------- | -------- | -------- | | 郵局詳情(目前使用的風景印圖片_地址_局名) | /api/locations/{location_id}/location_introduce | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get location introduce successfully", "result": { "message": "get posts from location successfully", "datas": [ { "id": 1, "name": "Zen location", "address": "fake address", "location_postmarks": [ { "id": 1, "postmark_img": "/images/upload/goodidea.png" } ] } ] } } ``` #### 失敗 422 ```{} { "status": "get location introduce failed", "result": { "message": "please enter the correct location id", "datas": [] } } ``` ## 郵局詳情(歷代風景印列表) [GET] [/api/locations/{location_id}/history_postmark_list] | 功能 | URL | Method | | -------- | -------- | -------- | | 郵局詳情(歷代風景印列表) | /api/locations/{location_id}/history_postmark_list | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get location introduction successfully", "result": { "message": "please enter the correct location id", "datas": [ { "id": 1, "locationName": "XX郵局", "address": "XX路XX號", "postmarks":[ { "postmark_img": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7" } ] } ] } } ``` ## 郵局歷代風景印詳情 [GET] [/api/locations/{location_id}/postmarks/{postmark_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | 郵局歷代風景印詳情 | /api/locations/{location_id}/postmarks/{postmark_id} | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded ``` #### Response #### 成功 200 ```{} { "status": "get location postmark content successfully", "result": { "message": "please enter the correct location id", "datas": [ { "id": 1, "startDate": "2020/6/7", "endDate": "null", "description": "XXX", "remark": "XXX" } ] } } ``` ## user新增風景印+遊記 [POST] [/api/postmark] | 功能 | URL | Method | | -------- | -------- | -------- | | user新增風景印+遊記 | /api/postmark | POST| #### Request ##### Headers ``` Accept:application/json apitoken: 使用者的apitoken ``` ##### Body |欄位名稱 | 資料型態 |備註| | -------- | -------- | -------- | |postmark_img|jpg, jpeg, png, gif|上傳圖檔| | locationName | string || | content | string || |imprintDate|string|| 範例格式 ``` { postmark_img: [upload_img_file], locationName: "XX郵局", content: "XXX", imprintDate: "2020/6/7" } ``` #### Response #### 成功 201 ```{} { "status": "upload postmark successfully", "result": { "message": "upload postmark successfully", "datas": [ { "id": 2, "postmark_img": "public/uploaded/img/01.jpg", "locationName": "XX郵局", "content": "XXX", "imprintDate": "2020/6/7" } ] } } ``` ## 收藏/解除收藏user的遊記 [PUT] [/api/collections/posts/{post_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | 收藏/解除收藏user的遊記 | /api/collections/posts/{post_id} | PUT| #### Request ##### Headers ``` Accept:application/json apitoken: 使用者的apitoken ``` #### Response #### 成功 201 ```{} { "status": "modify isCollection status successfully", "result": { "message": "modify isCollection status successfully", "datas": [] } ``` ## user收藏列表-城市列表 [GET] [/api/collections/] | 功能 | URL | Method | | -------- | -------- | -------- | | user收藏列表-城市列表 | /api/collections/ | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded apitoken: 使用者的apitoken ``` #### Response #### 成功 200 ```{} { "status": "get user's collections on city list successfully", "result": { "message": "get user's collections on city list successfully", "datas": [ { "distribute": "北區", "sub_distributes": [ { "sub_distribute": "東京都", "posts": [ {"id": 1, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, {"id": 2, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, {"id": 3, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, {"id": 4, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, ] } ] } ] } } ``` ## user收藏列表-郵局列表 [GET] [/api/collections/cities/{city_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | user收藏列表-郵局列表 | /api/collections/cities/{city_id} | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded apitoken: 使用者的apitoken ``` #### Response #### 成功 200 ```{ { "status": "get user's collections on location list successfully!", "result": { "message": "get user's collections on city list successfully", "datas": [ { "city": "東京都", "city_location": "XX郵局", "post": [ {"id": 1, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, {"id": 2, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, {"id": 3, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"}, {"id": 4, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7"} ] } ] } } ``` ## user收藏列表-該郵局的遊記列表 [GET] [/api/collections/cities/{city_id}/posts/{post_id}] | 功能 | URL | Method | | -------- | -------- | -------- | | user收藏列表-該郵局的遊記列表 | /api/collections/cities/{city_id}/posts/{post_id} | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded apitoken: 使用者的apitoken ``` #### Response #### 成功 200 ```{ { "status": "get user's collections on location successfully", "result": { "message": "get user's collections on location successfully", "datas": [ { "location": "XX郵局", "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7" } ] } } ``` ## user個人頁 [GET] [/api/profile] | 功能 | URL | Method | | -------- | -------- | -------- | | user個人頁 | /api/profile | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded apitoken: 使用者的apitoken ``` #### Response #### 成功 200 ```{} { "status": "get user's profile successfully", "result": { "message": "get user's profile successfully", "datas": [ { "name": "myName", "headImg": "public/uploaded/img/01.jpg", "uploadedPostmarks": [ { "id": 1, "postmarkImg": "public/uploaded/img/01.jpg", "imprintDate": "2020/6/7" } ] } ] } } ``` ## 修改user個人頁 [PUT] [/api/profile] | 功能 | URL | Method | | -------- | -------- | -------- | | 修改user個人頁 | /api/profile | PUT| #### Request ##### Headers ``` Accept:application/json apitoken: 使用者的apitoken ``` ##### Body |欄位名稱 | 資料型態 |備註| | -------- | -------- | -------- | | name | string || | headImg | jpg, jpeg, png, gif || 範例格式 ```{ { name: "newName", headImg: [profile_head_img_file] } ``` #### Response #### 成功 201 ```{} { "status": "modify profile successfully", "result": { "message": "modify profile successfully", "datas": [ { "id": 2, "name": "newName", "headImg": "public/uploaded/img/01.jpg" } ] } } ``` ## 郵局所有的遊記詳情列表 [GET] [/api/locations/{location_id}/post] | 功能 | URL | Method | | -------- | -------- | -------- | | 郵局所有的遊記詳情列表 | /api/locations/{location_id}/post | GET| #### Request ##### Headers ``` Content-Type: application/x-www-form-urlencoded apitoken: 使用者的apitoken ``` #### Response #### 成功 200 ```{} { "status": "get all post of the location successfully", "result": { "message": "modify profile successfully", "datas": [ { "id": 1, "postmark_img": "public/uploaded/img/01.jpg", "isCollection": 0, "imprintDate": "2020/6/7", "content": "XXX" } ] } }

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.