owned this note
owned this note
Published
Linked with GitHub
# 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"
}
]
}
}