---
# System prepended metadata

title: API 文件
tags: [Lidemy]

---

---
tags: Lidemy
---
# API 文件

### [第三方 API](https://hackmd.io/Wn08L-1uQ125R7g2G12uLQ)

## Root Path

* domain/api/v1/
    專案使用： https://api.wandermap.tw/api/v1/test
    備份： https://backup.wandermap.tw/api/v1/test

## Endpoints

### 文件頁

範例： domain/api/v1/doc

|Description|Method|Path|Parameter|Role|
|-----------|:----:|----|---------|----|
|API 文件|GET|/doc|-|-|
|API 測試|GET|/test|-|-|

文件： HackMD 的 API 文件
測試： 由 swagger 產生

### [使用者 User](#User)

範例：domain/api/v1/users

|Description|Method|Path|Parameter|Role|
|-----------|:----:|----|---------|----|
|[註冊使用者](#註冊使用者)|POST|/users/register|-|-|
|[使用者登入](#使用者登入)|POST|/users/login|-|-|
|[以 refresh token 取得 access token](#以-refresh-token-取得-access-token)|GET|/users/refresh|-|member|
|[使用者登出](#使用者登出)|GET|/users/logout|-|member|
|[取得所有使用者資料](#取得所有使用者資料)|GET|/users|limit=20、offset、cursor|admin|
|[取得單一使用者資料](#取得單一使用者資料)|GET|/users/&lt;user ID&gt;|-|-|
|[修改使用者資料](#修改使用者資料)|PATCH|/users/&lt;user ID&gt;|-|member|
|[取得某使用者下的所有 todo](#取得某使用者下的所有-todo)|GET|/users/&lt;user ID&gt;/todos|-|member|
|[新增 todo](#新增-todo)|POST|/users/&lt;user ID&gt;/todos|-|member|
|[修改 todo](#修改-todo)|PATCH|/users/&lt;user ID&gt;/todos/&lt;todo ID&gt;|-|member|
|[刪除 todo](#刪除-todo)|DELETE|/users/&lt;user ID&gt;/todos/&lt;todo ID&gt;|-|member|
|[取得屬於使用者的所有心得](#取得屬於使用者的所有心得)|GET|/users/&lt;user ID&gt;/articles|limit、offsest、cursor、tag|-|
|[取得使用者按讚的心得](#取得使用者按讚的心得)|GET|/users/&lt;user ID&gt;/liked-articles|limit、offsest、cursor、tag|-|
|[使用者對心得按讚](#使用者對心得按讚/取消按讚)|POST|/users/&lt;user ID&gt;/liked-articles|-|member|
|[使用者對心得取消按讚](#使用者對心得按讚/取消按讚)|DELETE|/users/&lt;user ID&gt;/liked-articles/&lt;article ID&gt;|-|member|
|[取得屬於使用者的所有步道](#取得屬於使用者的所有步道)|GET|/users/&lt;user ID&gt;/trails|limit、offsest、cursor、filter|-|
|[取得使用者收藏的步道](#取得使用者收藏的步道)|GET|/users/&lt;user ID&gt;/collected-trails|limit、offsest、cursor、filter|-|
|[使用者收藏步道](#使用者收藏/取消收藏步道)|POST|/users/&lt;user ID&gt;/collected-trails|-|member  |
|[使用者取消收藏步道](#使用者收藏/取消收藏步道)|DELETE|/users/&lt;user ID&gt;/collected-trails/&lt;trail ID&gt;|-|member |

### [心得 Article](#Article)

範例：domain/api/v1/articles

|Description|Method|Path|Parameter|Role|
|-----------|:----:|----|---------|--------------|
|[新增心得](#新增心得)|POST|/articles|-|member|
|[取得所有心得](#取得所有心得)|GET|/articles|limit、offset、cursor、tag、search|-|
|[取得按讚最多的心得](#取得按讚最多的心得)|GET|/articles/hot|limit、offset、cursor、tag|-|
|[取得單一心得](#取得單一心得)|GET|/articles/&lt;article ID&gt;|-|-|
|[修改心得](#修改心得)|PATCH|/articles/&lt;article ID&gt;|-|member|
|[刪除心得](#刪除心得)|DELETE|/articles/&lt;article ID&gt;|-|member|
|[取得某心得的留言](#取得某心得的留言)|GET|/articles/&lt;article ID&gt;/messages|~~limit、offset、cursor~~|-|
|[新增某心得的留言](#新增某心得的留言)|POST|/articles/&lt;article ID&gt;/messages|-|member|
|[更新某心得的留言](#更新某心得的留言)|PATCH|/articles/&lt;article ID&gt;/messages/&lt;message ID&gt;|-|member|
|[刪除某心得的留言](#刪除某心得的留言)|DELETE|/articles/&lt;article ID&gt;/messages/&lt;message ID&gt;|-|member|
|[取得所有已刪除心得](#取得所有已刪除心得)|GET|/articles/deleted|-|admin|
|[恢復某已刪除的心得](#恢復某已刪除的心得)|PATCH|/articles/deleted/&lt;article ID&gt;|-|admin|

### [步道 Trail](#Trail)

範例：domain/api/v1/trails

|Description|Method|Path|Parameter|Role|
|-----------|:----:|----|---------|--------------|
|[新增步道](#新增步道)|POST|/trails|-|admin|
|[取得所有步道](#取得所有步道)|GET|/trails|limit、offset、cursor、filter、search|-|
|[取得收藏數最多步道](#取得收藏數最多步道)|GET|/trails/hot/<Num>|-|-|
|[取得單一步道](#取得單一步道)|GET|/trails/&lt;trail ID&gt;|-|-|
|[修改步道](#修改步道)|PATCH|/trails/&lt;trail ID&gt;|-|admin|
|[刪除步道](#刪除步道)|DELETE|/trails/&lt;trail ID&gt;|-|admin|
|[取得某步道的心得](#取得某步道的心得)|GET|/trails/&lt;trail ID&gt;/articles|limit、offset、cursor|-|
|[取得某步道的評論](#取得某步道的評論)|GET|/trails/&lt;trail ID&gt;/comments|~~limit、offset、cursor~~|-|
|[新增某步道的評論](#新增某步道的評論)|POST|/trails/&lt;trail ID&gt;/comments|-|member|
|[更新某步道的評論](#更新某步道的評論)|PATCH|/trails/&lt;trail ID&gt;/comments/&lt;comment ID&gt;|-|member|
|[刪除某步道的評論](#刪除某步道的評論)|DELETE|/trails/&lt;trail ID&gt;/comments/&lt;comment ID&gt;|-|member|
|[取得所有已刪除步道](#取得所有已刪除步道)|GET|/trails/deleted|-|admin|
|[恢復某已刪除的步道](#恢復某已刪除的步道)|PATCH|/trails/deleted/&lt;trail ID&gt;|-|admin|

## Details

各 endpoint 之下 request 和 response 的範例。

### User

#### 註冊使用者

Request Example

```json=
{
  nickname: "Dylan",
  email: "abc@email.com",
  password: "abc123",
  confirmPassword: "abc123"
}
```

Response Example
```json=
{
  "success": true,
  "message": "registration success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1NCwibmlja25hbWUiOiJ6enp6IiwiZW1haWwiOiJ6enp6QGdtYWlsLmNvbSIsImljb25fdXJsIjpudWxsLCJyb2xlIjoibWVtYmVyIiwidXBkYXRlZF9hdCI6IjIwMjEtMTAtMTRUMDE6MDI6MjIuMDAwWiIsImNyZWF0ZWRfYXQiOiIyMDIxLTEwLTE0VDAxOjAyOjIyLjAwMFoiLCJpYXQiOjE2MzQyMDIxNDIsImV4cCI6MTYzNDIwNTc0Mn0.7YHPLQSZv5fUWrcve-JKDXp_42zsP-kVCwEiYsZUNOE"
  }
}
```

#### 使用者登入

Request Example

```json=
{
  email: "abc@email.com",
  password: "abc123"
}
```

Response Example

```json=
{
  "success": true,
  "message": "logged in",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1Mywibmlja25hbWUiOiJ6enoiLCJlbWFpbCI6Inp6ekBnbWFpbC5jb20iLCJpY29uX3VybCI6bnVsbCwicm9sZSI6ImFkbWluIiwidXBkYXRlZF9hdCI6IjIwMjEtMTAtMTNUMTk6NTM6NDYuMDAwWiIsImNyZWF0ZWRfYXQiOiIyMDIxLTEwLTExVDIzOjEyOjE2LjAwMFoiLCJpYXQiOjE2MzQyMDIyMjEsImV4cCI6MTYzNDIwNTgyMX0.CV57kxJ_V9nuCyE6IK2YRLhjQXaj-FS-jPjmurOVves"
  }
}
```

#### 以 refresh token 取得 access token
Response Example

使用者登入、註冊時 response header 會包含 `Set-Cookie: refreshToken=XXX`。
request 時，header 帶上 `Cookie: refreshToken=XXX` 就可以取得 access token 和新的 refresh token。

```json=
{
  "success": true,
  "message": "jwt access token",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1Mywibmlja25hbWUiOiJ6enoiLCJlbWFpbCI6Inp6ekBnbWFpbC5jb20iLCJpY29uX3VybCI6bnVsbCwicm9sZSI6ImFkbWluIiwidXBkYXRlZF9hdCI6IjIwMjEtMTAtMTNUMTk6NTM6NDYuMDAwWiIsImNyZWF0ZWRfYXQiOiIyMDIxLTEwLTExVDIzOjEyOjE2LjAwMFoiLCJpYXQiOjE2MzQyMDIzMjksImV4cCI6MTYzNDIwNTkyOX0.NYtV_QLTXiG-t8hBnWm576n4qI5nODVsFtVqXLjFZIA"
  }
}
```

#### 使用者登出

將 refresh token cookie 清除。

Response Example

```json=
{
  "success": true,
  "message": "logged out",
  "data": {}
}
```

#### 取得所有使用者資料

Reaponse Example

```json=
{
  "success": true,
  "message": "user data",
  "data": {
    "users": [
      {
        "user_id": 1,
        "nickname": "小火龍",
        "email": "123@gmail.com",
        "icon_url": "https://example.com/charmander.png",
        "role": "member",
        "updated_at": "2021-10-12T02:39:17.000Z",
        "created_at": "2021-09-20T20:52:20.000Z"
      },
      {
        "user_id": 2,
        "nickname": "傑尼龜",
        "email": "1323@gmail.com",
        "icon_url": "https://example.com/squirtle.png",
        "role": "member",
        "updated_at": "2021-10-12T02:39:17.000Z",
        "created_at": "2021-09-20T20:53:24.000Z"
      }
    ]
  }
}
```

#### 取得單一使用者資料

Response Example

```json=
{
  "success": true,
  "message": "get user data",
  "data": {
    "user_id": 1,
    "nickname": "小火龍",
    "email": "123@gmail.com",
    "icon_url": "https://example.com/charmander.png",
    "role": "member",
    "updated_at": "2021-10-12T02:39:17.000Z",
    "created_at": "2021-09-20T20:52:20.000Z"
  }
}
```

#### 修改使用者資料

Request Example

```json=
{
  nickname: 'totorai',
  icon_url: 'https://example2.com',
  password: '123',
  confirmPassword: '123'
}
```

Response Example
```json=
{
  "success": true,
  "message": "user_id: 11 is updated",
  "data": {}
}
```

#### 取得某使用者下的所有 todo

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": {
    "todos": [
      {
        "todo_id": 1,
        "user_id": 1,
        "content": "待辦事項1",
        "is_done": 0,
        "updated_at": "2021-09-23T21:30:42.000Z",
        "created_at": "2021-09-23T04:29:11.000Z"
      },
      {
        "todo_id": 2,
        "user_id": 1,
        "content": "待辦事項2",
        "is_done": 0,
        "updated_at": "2021-09-26T04:24:56.000Z",
        "created_at": "2021-09-23T06:47:08.000Z"
      }
    ]
  }
}
```

#### 新增 todo

Request Example

```json=
{
  content: '待辦事項5',
  is_done: 0
}
```

Response Example

```json=
{
  "success": true,
  "message": "created",
  "data": {
    "result": {
      "fieldCount": 0,
      "affectedRows": 1,
      "insertId": 12,
      "info": "",
      "serverStatus": 2,
      "warningStatus": 0
    }
  }
}
```

#### 修改 todo

Request Example

```json=
{
  content: '做完的待辦事項'
  is_done: 1
}
```

Response Example

```json=
{
  "success": true,
  "message": "updated",
  "data": {
    "result": {
      "fieldCount": 0,
      "affectedRows": 1,
      "insertId": 0,
      "info": "Rows matched: 1  Changed: 1  Warnings: 0",
      "serverStatus": 2,
      "warningStatus": 0,
      "changedRows": 1
    }
  }
}
```

#### 刪除 todo

Response Example

```json=
{
  "success": true,
  "message": "deleted",
  "data": {
    "result": {
      "fieldCount": 0,
      "affectedRows": 1,
      "insertId": 0,
      "info": "",
      "serverStatus": 2,
      "warningStatus": 0
    }
  }
}
```

#### 取得屬於使用者的所有心得

Response Example

```json=
{
  "success": true,
  "message": "articles wrote by user 1",
  "data": {
    "articles": [
      {
        "article_id": 1,
        "author_id": 1,
        "title": "金面山剪刀石一日遊",
        "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industrys standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
        "location": "台北市內湖區",
        "coordinate": {
          "x": 23,
          "y": 24
        },
        "altitude": 87,
        "length": 5,
        "departure_time": "2020-12-22T13:14:57.000Z",
        "end_time": "2020-12-22T15:14:57.000Z",
        "time_spent": 2,
        "cover_picture_url": "https://i.imgur.com/w2Y6y4z.jpg",
        "gpx_url": "XXX",
        "views": 0,
        "is_deleted": 0,
        "updated_at": "2021-10-05T23:14:46.000Z",
        "created_at": "2021-09-27T00:40:26.000Z",
        "tag_names": "一日, 夜景, 稀有動植物, 有水源"
      }
    ]
  }
}
```

#### 取得使用者按讚的心得

Response Example

```json=
{
  "success": true,
  "message": "articles liked by user 1",
  "data": {
    "articles": [
      {
        "article_id": 1,
        "author_id": 1,
        "title": "金面山剪刀石一日遊",
        "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industrys standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
        "location": "台北市內湖區",
        "coordinate": {
          "x": 23,
          "y": 24
        },
        "altitude": 87,
        "length": 5,
        "departure_time": "2020-12-22T13:14:57.000Z",
        "end_time": "2020-12-22T15:14:57.000Z",
        "time_spent": 2,
        "cover_picture_url": "https://i.imgur.com/w2Y6y4z.jpg",
        "gpx_url": "XXX",
        "views": 0,
        "is_deleted": 0,
        "updated_at": "2021-10-05T23:14:46.000Z",
        "created_at": "2021-09-27T00:40:26.000Z",
        "tag_names": "一日, 夜景, 稀有動植物, 有水源"
      }
    ]
  }
}
```

#### 使用者對心得按讚

Request Example

```json=
{
  articleId: 1
}
```

Response Example

```json=
{
  "success": true,
  "message": "like association was created",
  "data": {
    "results": {
      "fieldCount": 0,
      "affectedRows": 1,
      "insertId": 0,
      "info": "Records: 1  Duplicates: 0  Warnings: 0",
      "serverStatus": 2,
      "warningStatus": 0
    }
  }
}
```

#### 使用者對心得取消按讚

Response Example

```json=
{
  "success": true,
  "message": "like association was deleted",
  "data": {
    "results": {
      "fieldCount": 0,
      "affectedRows": 1,
      "insertId": 0,
      "info": "",
      "serverStatus": 2,
      "warningStatus": 0
    }
  }
}
```

#### 取得屬於使用者的所有步道

Response Example

```json=
{
  "success": true,
  "message": "trails wrote by user 1",
  "data": {
    "trails": [
      {
        "trail_id": 4,
        "author_id": 1,
        "title": "金瓜寮魚蕨步道",
        "description": "金瓜寮魚蕨步道位於坪林，步道南北端皆可出入。步道有拱橋及觀景平臺，有較多階梯，走出南出口後向南續行可連接到觀魚蕨類步道。全線沿著金瓜寮溪蜿蜒行進，溪水淙淙，可觀苦花魚、馬口魚等，亦有多種蕨類，適合親子出遊。",
        "location": "新北市坪林區",
        "coordinate": {
          "x": 121.67445749552773,
          "y": 24.90320217138141
        },
        "altitude": 300,
        "length": 1.06,
        "season": null,
        "difficulty": "lowest",
        "cover_picture_url": "https://live.staticflickr.com/8604/16032975448_a9c3d16b46_c.jpg",
        "map_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/004/01/004map.jpg",
        "required_time": "半天",
        "rating": null,
        "situation": "枕木階梯、土徑",
        "gpx_url": null,
        "views": 0,
        "is_deleted": 0,
        "updated_at": "2021-09-22T06:39:01.000Z",
        "created_at": "2021-09-22T06:39:01.000Z"
      }
    ]
  }
}
```

#### 取得使用者收藏的步道

Response Example

```json=
{
  "success": true,
  "message": "trails collected by user 7",
  "data": {
    "trails": [
      {
        "trail_id": 5,
        "author_id": 1,
        "title": "拳頭姆自然步道",
        "description": "海拔三百多公尺的拳頭姆山位於宜蘭縣三星鄉境內天送埤地區，步道入口位於臺7丙9.5公里處，步道坡度平緩，行走輕鬆，步道環境為烏心石造林地，有豐富的蕨類與多樣的植物，隨著時序變化展現不同風情，也為鳥類及各種小生物提供良好的棲息環境；登頂可以俯瞰蘭陽溪及蘭陽平原，遙望中央山脈與雪山山脈。 \r\n\r\n拳頭姆步道原為荒草蔓生的舊林道，經林務局以自然工法施設整修、並搭建觀景平臺，成為穿梭在林務局羅東事業區47林班烏心石與肖楠造林地的生態步道。以如拳頭般山頭命名的拳頭姆步道，於民國96年9月中旬啟用。\r\n",
        "location": "宜蘭縣三星鄉",
        "coordinate": {
          "x": 121.61441173746651,
          "y": 24.656121980645736
        },
        "altitude": 310,
        "length": 1.3,
        "season": "四季皆宜",
        "difficulty": "lowest",
        "cover_picture_url": "https://live.staticflickr.com/8457/7999249230_47be267600_b.jpg",
        "map_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/005/01/005_MAP.jpg",
        "required_time": "半天",
        "rating": null,
        "situation": "原木及碎木屑鋪設",
        "gpx_url": null,
        "views": 0,
        "is_deleted": 0,
        "updated_at": "2021-09-22T06:39:02.000Z",
        "created_at": "2021-09-22T06:39:02.000Z"
      }
    ]
  }
}
```
#### 使用者收藏步道

Request Example

```json=
{
  trail_id: 15
}
```

Response Example

```json=
{
  "success": true,
  "message": "collect association was created",
  "data": {
    "result": {
      "fieldCount": 0,
      "affectedRows": 1,
      "insertId": 0,
      "info": "Records: 1  Duplicates: 0  Warnings: 0",
      "serverStatus": 2,
      "warningStatus": 0
    }
  }
}
```

#### 使用者取消收藏步道

Response Example

```json=
{
  "success": true,
  "message": "collect association was deleted",
  "data": {
    "result": {
      "fieldCount": 0,
      "affectedRows": 0,
      "insertId": 0,
      "info": "",
      "serverStatus": 2,
      "warningStatus": 0
    }
  }
}
```

### Article

#### 新增心得

Request Example

```json=
{
  author_id: 1,
  tags: ['夜景', '有水源'],
  title: '枕頭山遊記',
  content: 'Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industrys standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.',
  location: '新竹縣五峰鄉',
  coordinate: { x: 24.629966069401192, y: 121.1194297010909 },
  altitude: 87,
  length: 5,
  departure_time: '2020-12-22 21:14:57',
  end_time: '2020-12-22 23:14:57',
  time_spent: 2,
  cover_picture_url: 'https://example.com/pic.png',
  gpx_url: 'https://example.com/trail.gpx'
}
```

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": {
    "fieldCount": 0,
    "affectedRows": 2,
    "insertId": 0,
    "info": "Records: 2  Duplicates: 0  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 取得所有心得

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": [
    {
      "article_id": 1,
      "author_id": 1,
      "title": "金面山剪刀石一日遊",
      "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industrys standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
      "location": "台北市內湖區",
      "coordinate": {
        "x": 23,
        "y": 24
      },
      "altitude": 87,
      "length": 5,
      "departure_time": "2020-12-22T13:14:57.000Z",
      "end_time": "2020-12-22T15:14:57.000Z",
      "time_spent": 2,
      "cover_picture_url": "https://i.imgur.com/w2Y6y4z.jpg",
      "gpx_url": "XXX",
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-05T23:14:46.000Z",
      "created_at": "2021-09-27T00:40:26.000Z",
      "tag_names": "一日, 夜景, 稀有動植物, 有水源"
    }
  ]
}
```

#### 取得按讚最多的心得

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": [
    {
      "article_id": 1,
      "author_id": 1,
      "title": "金面山剪刀石一日遊",
      "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industrys standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
      "location": "台北市內湖區",
      "coordinate": {
        "x": 23,
        "y": 24
      },
      "altitude": 87,
      "length": 5,
      "departure_time": "2020-12-22T13:14:57.000Z",
      "end_time": "2020-12-22T15:14:57.000Z",
      "time_spent": 2,
      "cover_picture_url": "https://i.imgur.com/w2Y6y4z.jpg",
      "gpx_url": "XXX",
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-05T23:14:46.000Z",
      "created_at": "2021-09-27T00:40:26.000Z",
      "tag_names": "一日, 夜景, 稀有動植物, 有水源"
    }
  ]
}
```

#### 取得單一心得

Response Example

```json=
{
  "success": true,
  "message": "get article-id 23",
  "data": [
    {
      "article_id": 23,
      "author_id": 1,
      "title": "00000000000000",
      "content": "0000000000",
      "location": null,
      "coordinate": null,
      "altitude": null,
      "length": null,
      "departure_time": null,
      "end_time": null,
      "time_spent": null,
      "cover_picture_url": null,
      "gpx_url": null,
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-11T05:55:10.000Z",
      "created_at": "2021-10-11T05:55:10.000Z",
      "tag_names": null,
      "trail_title": null
    }
  ]
}
```

#### 修改心得

Request Example

```json=
{
  title: '金面山剪刀石5566',
  content: '56不能亡',
  location: '台北市士林區區',
  coordinate: {x: 556677, y: 0},
  altitude: 55,
  length: 5,
  departure_time: '2020-12-22 21:14:57',
  end_time: '2020-12-22 21:14:57',
  time_spent: 2,
  cover_picture_url: 'https://example.com/pic.png',
  gpx_url: 'https://example.com/trail.gpx',
  is_deleted: 0,
  tags: ['一日', '賞花', 'GPX']
}
```

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": [
    {
      "article_id": 23,
      "author_id": 1,
      "title": "金面山剪刀石5566",
      "content": "56不能亡",
      "location": "台北市士林區區",
      "coordinate": {
        "x": 556677,
        "y": 0
      },
      "altitude": null,
      "length": null,
      "departure_time": null,
      "end_time": null,
      "time_spent": null,
      "cover_picture_url": null,
      "gpx_url": null,
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-14T03:09:38.000Z",
      "created_at": "2021-10-11T05:55:10.000Z",
      "tag_names": "賞花, GPX",
      "trail_title": null
    }
  ]
}
```

#### 刪除心得

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "Rows matched: 1  Changed: 1  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0,
    "changedRows": 1
  }
}
```

#### 取得某心得的留言

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": [
    {
      "message_id": 1,
      "author_id": 1,
      "article_id": 2,
      "content": "有看到珍奇異獸嗎",
      "is_deleted": 0,
      "updated_at": "2021-10-10T19:55:08.000Z",
      "created_at": "2021-10-03T01:00:08.000Z",
      "user_id": 1,
      "nickname": "小火龍",
      "icon_url": "https://tw.portal-pokemon.com/play/resources/pokedex/img/pm/d0ee81f16175c97770192fb691fdda8da1f4f349.png"
    },
    {
      "message_id": 5,
      "author_id": 36,
      "article_id": 2,
      "content": "最近路好走嗎",
      "is_deleted": 0,
      "updated_at": "2021-10-10T19:37:22.000Z",
      "created_at": "2021-10-10T19:01:20.000Z",
      "user_id": 36,
      "nickname": "小美",
      "icon_url": null
    }
  ]
}
```

#### 新增某心得的留言

Request Example
```json=
{
  content: '最近路好走嗎'
}
```

Response Example
```json=
{
  "success": true,
  "message": "OK",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 10,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 更新某心得的留言

Request Example
```json=
{
  content: '最近路況如何'
}
```

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 11,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 刪除某心得的留言

Response Example

```json=
{
  "success": true,
  "message": "OK",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 新增某心得與步道的關聯

Request Example

```json=
{
  trail_id: 21
}
```

Response Example
```json=
{
  "success": true,
  "message": "article-1 linked to trail-21",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 刪除某心得與步道的關聯

Response Example

```json=
{
  "success": true,
  "message": "article-1 unlinked to trail-21",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 取得所有已刪除心得
Response Example
```json=
{
  "success": true,
  "message": "get all deleted articles",
  "data": [
    {
      "article_id": 20,
      "author_id": 16,
      "title": "金面山剪刀石一百一十日遊魚遊戲",
      "content": "再來試試看",
      "location": null,
      "coordinate": null,
      "altitude": null,
      "length": null,
      "departure_time": null,
      "end_time": null,
      "time_spent": null,
      "cover_picture_url": null,
      "gpx_url": null,
      "views": 0,
      "is_deleted": 1,
      "updated_at": "2021-10-05T01:12:25.000Z",
      "created_at": "2021-10-05T00:44:56.000Z",
      "tag_names": null
    },
    {
      "article_id": 21,
      "author_id": 1,
      "title": "石門東稜",
      "content": "嗨嗨嗨，測看看",
      "location": null,
      "coordinate": null,
      "altitude": null,
      "length": null,
      "departure_time": null,
      "end_time": null,
      "time_spent": null,
      "cover_picture_url": null,
      "gpx_url": null,
      "views": 0,
      "is_deleted": 1,
      "updated_at": "2021-10-14T03:18:49.000Z",
      "created_at": "2021-10-10T20:42:30.000Z",
      "tag_names": null
    }
  ]
}
```
#### 恢復某已刪除的心得
Response Example
```json=
{
  "success": true,
  "message": "recover article-6",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "Rows matched: 1  Changed: 1  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0,
    "changedRows": 1
  }
}
```

### Trail

#### 新增步道

Request Example

```json=
{
  author_id: 'torai',
  title: '枕頭山步道',
  description: '空氣清新，環境優美。',
  location: '南投縣仁愛鄉',
  coordinateX: 121.1194297010909,
  coordinateY: 24.629966069401192,
  altitude: 1000,
  length: 500,
  difficulty: '進階',
  situation: '土徑',
  season: '春',
  cover_picture_url: 'https://example.com',
  map_picture_url: 'https://example.com',
  required_time: 8,
  gpx_url: 'https://example.com'
}
```

Response Example

```json=
{
  "success": true,
  "message": "add trail-128",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 128,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```


#### 取得所有步道

Response Example

```json=
{
  "success": true,
  "message": "get {\"limit\":1} trails",
  "data": [
    {
      "trail_id": 1,
      "author_id": 1,
      "title": "蘇花古道：大南澳越嶺段",
      "description": "蘇花古道建造於清朝同治13 年(1874 年)，是聯絡蘇澳與花蓮之間最早的一條官道；日人19 世紀於蘇花海岸之間先後開鑿了北段的大南澳路、南段的沿岸理番道路及東海徒步道，即今日蘇花公路的前身，但早已荒廢舊跡難尋。經過調查後整建「蘇花古道-- 大南澳越嶺段」。 \r\n\r\n古道呈南北縱向，北側為軍方管制道路無法通行，建議由南側登山口往北走再折返，海拔落差近七百公尺，來回行走約5小時，路程頗具挑戰性。 從南口入古道，一路陡上，約十餘分鐘後抵達一處較平緩的空曠處，路旁有處碉堡遺跡以及水泥護欄，此為崩坍廢棄的舊蘇花公路。\r\n\r\n沿路隔著樹林間隙，可以遙望汪洋大海。在1.2 K里程處抵達休息平臺，即是南澳嶺的主峰所在，再攀至0.6 公里附近的觀景臺，古道在此豁然開朗。繼續陡下至鞍部，再爬坡至烏石鼻戰備道路上的北端起點。\r\n",
      "location": "宜蘭縣南澳鄉",
      "coordinate": {
        "x": 121.83785521632522,
        "y": 24.482340609862774
      },
      "altitude": 650,
      "length": 4.1,
      "season": "四季皆宜",
      "difficulty": "入門",
      "cover_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/001/05/001.jpg",
      "map_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/001/01/001_MAP201902152.jpg",
      "required_time": "一天",
      "rating": null,
      "situation": "土徑步道、土木階梯",
      "gpx_url": null,
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-14T04:45:39.000Z",
      "created_at": "2021-09-22T06:39:00.000Z"
    }
  ]
}
```

#### 取得收藏數最多步道

Response Example

```json=
{
  "success": true,
  "message": "get top-2 hot trails",
  "data": [
    {
      "trail_id": 5,
      "author_id": 1,
      "title": "拳頭姆自然步道",
      "description": "海拔三百多公尺的拳頭姆山位於宜蘭縣三星鄉境內天送埤地區，步道入口位於臺7丙9.5公里處，步道坡度平緩，行走輕鬆，步道環境為烏心石造林地，有豐富的蕨類與多樣的植物，隨著時序變化展現不同風情，也為鳥類及各種小生物提供良好的棲息環境；登頂可以俯瞰蘭陽溪及蘭陽平原，遙望中央山脈與雪山山脈。 \r\n\r\n拳頭姆步道原為荒草蔓生的舊林道，經林務局以自然工法施設整修、並搭建觀景平臺，成為穿梭在林務局羅東事業區47林班烏心石與肖楠造林地的生態步道。以如拳頭般山頭命名的拳頭姆步道，於民國96年9月中旬啟用。\r\n",
      "location": "宜蘭縣三星鄉",
      "coordinate": {
        "x": 121.61441173746651,
        "y": 24.656121980645736
      },
      "altitude": 310,
      "length": 1.3,
      "season": "四季皆宜",
      "difficulty": "新手",
      "cover_picture_url": "https://live.staticflickr.com/8457/7999249230_47be267600_b.jpg",
      "map_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/005/01/005_MAP.jpg",
      "required_time": "半天",
      "rating": null,
      "situation": "原木及碎木屑鋪設",
      "gpx_url": null,
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-14T04:43:39.000Z",
      "created_at": "2021-09-22T06:39:02.000Z"
    },
    {
      "trail_id": 6,
      "author_id": 1,
      "title": "松羅步道",
      "description": "松羅步道依昔日泰雅獵徑整修而成。步道沿著松羅溪而行，林蔭蒼蒼，溪水淙淙，著生殖物繁盛，是步道最大的特色。低海拔及濕潤的環境，造就了雨林般的森林植被原始景觀。沿途松羅溪一路陪伴，可以在水中清楚看到近年保育的成果「臺灣?魚」優游其中，似乎也能感受到牠們的自在與喜樂。步道最讓人驚豔的是擁有其他步道無法相比的濕生動植物，以生意盎然的姿態在此生長，如濃密的山蘇隧道、大面積蕨類植物、隨處飛舞的蜻蜓等，彷彿置身亞馬遜。\r\n為了維護原始生態環境，自然步道皆是就地取材施作，儘量不使用違背原始自然生態的人工建材，因此行走起來特別舒服、也特別能融入於這片美麗的自然中。\r\n",
      "location": "宜蘭縣大同鄉",
      "coordinate": {
        "x": 121.5628487476976,
        "y": 24.66858465717884
      },
      "altitude": 400,
      "length": 2,
      "season": "四季皆宜",
      "difficulty": "新手",
      "cover_picture_url": "https://p.timelog.to/2/w/0/223/FBNt_800.jpg",
      "map_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/006/01/006map.jpg",
      "required_time": "半天",
      "rating": null,
      "situation": "石子路",
      "gpx_url": null,
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-14T04:43:39.000Z",
      "created_at": "2021-09-22T06:39:02.000Z"
    }
  ]
}
```

#### 取得單一步道

Response Example

```json=
{
  "success": true,
  "message": "get trail-1 info",
  "data": [
    {
      "trail_id": 1,
      "author_id": 1,
      "title": "蘇花古道：大南澳越嶺段",
      "description": "蘇花古道建造於清朝同治13 年(1874 年)，是聯絡蘇澳與花蓮之間最早的一條官道；日人19 世紀於蘇花海岸之間先後開鑿了北段的大南澳路、南段的沿岸理番道路及東海徒步道，即今日蘇花公路的前身，但早已荒廢舊跡難尋。經過調查後整建「蘇花古道-- 大南澳越嶺段」。 \r\n\r\n古道呈南北縱向，北側為軍方管制道路無法通行，建議由南側登山口往北走再折返，海拔落差近七百公尺，來回行走約5小時，路程頗具挑戰性。 從南口入古道，一路陡上，約十餘分鐘後抵達一處較平緩的空曠處，路旁有處碉堡遺跡以及水泥護欄，此為崩坍廢棄的舊蘇花公路。\r\n\r\n沿路隔著樹林間隙，可以遙望汪洋大海。在1.2 K里程處抵達休息平臺，即是南澳嶺的主峰所在，再攀至0.6 公里附近的觀景臺，古道在此豁然開朗。繼續陡下至鞍部，再爬坡至烏石鼻戰備道路上的北端起點。\r\n",
      "location": "宜蘭縣南澳鄉",
      "coordinate": {
        "x": 121.83785521632522,
        "y": 24.482340609862774
      },
      "altitude": 650,
      "length": 4.1,
      "season": "四季皆宜",
      "difficulty": "入門",
      "cover_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/001/05/001.jpg",
      "map_picture_url": "https://recreation.forest.gov.tw/Files/RT/Photo/001/01/001_MAP201902152.jpg",
      "required_time": "一天",
      "rating": null,
      "situation": "土徑步道、土木階梯",
      "gpx_url": null,
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-14T04:45:39.000Z",
      "created_at": "2021-09-22T06:39:00.000Z"
    }
  ]
}
```

#### 修改步道

Request Example

```json=
{
  author_id: 1,
  title: '測測測試',
  description: '敘述術述',
  location: '新竹縣埔埔鄉',
  coordinateX: 5,
  coordinateY: 6,
  altitude: 5,
  length: 88,
  difficulty: 3,
  situation: 'wuwuw',
  required_time: '一天',
  season: '春',
  cover_picture_url: 'http://example.com/pic.png',
  map_picture_url: 'http://example.com/pic.png'
}
```

Response Example

```json=
{
  "success": true,
  "message": "update trail-127",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "Rows matched: 1  Changed: 1  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0,
    "changedRows": 1
  }
}
```

#### 刪除步道

Response Example

```json=
{
  "success": true,
  "message": "trail-128 deleted",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "Rows matched: 1  Changed: 1  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0,
    "changedRows": 1
  }
}
```

#### 取得某步道的心得

Response Example

```json=
{
  "success": true,
  "message": "articles of trail-1",
  "data": [
    {
      "tag_names": "一日, 海景, 夜景, 山景, 城市景色, 登山小白體驗",
      "author_name": "小火龍",
      "icon_url": "https://tw.portal-pokemon.com/play/resources/pokedex/img/pm/d0ee81f16175c97770192fb691fdda8da1f4f349.png",
      "article_id": 2,
      "author_id": 1,
      "title": "熊空秘境探險",
      "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industrys standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
      "location": "台北市內湖區",
      "coordinate": {
        "x": 24.629966069401192,
        "y": 121.1194297010909
      },
      "altitude": 87,
      "length": 5,
      "departure_time": "2020-12-22T13:14:57.000Z",
      "end_time": "2020-12-22T15:14:57.000Z",
      "time_spent": 2,
      "cover_picture_url": "https://i.imgur.com/w2Y6y4z.jpg",
      "gpx_url": "XXX",
      "views": 0,
      "is_deleted": 0,
      "updated_at": "2021-10-05T23:14:47.000Z",
      "created_at": "2021-09-29T23:53:30.000Z"
    }
  ]
}
```

#### 取得某步道的評論

Response Example

```json=
{
  "success": true,
  "message": "get trail-1 comments",
  "data": [
    {
      "comment_id": 1,
      "trail_id": 1,
      "author_id": 1,
      "content": "我才是頭香啦",
      "is_deleted": 0,
      "updated_at": "2021-10-04T02:36:13.000Z",
      "created_at": "2021-10-04T02:36:13.000Z",
      "user_id": 1,
      "nickname": "小火龍",
      "icon_url": "https://tw.portal-pokemon.com/play/resources/pokedex/img/pm/d0ee81f16175c97770192fb691fdda8da1f4f349.png"
    }
  ]
}
```

#### 新增某步道的評論

Request Example
```json=
{
  trail_id: 1,
  author_id: 1,
  content: '寫得很棒'
}
```

Response Example
```json=
{
  "success": true,
  "message": "leave trail-1 comment: 66大順",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 30,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 更新某步道的評論

Request Example
```json=
{
  author_id: 1,
  content: '寫得真是太棒了'
}
```

Response Example
```json=
{
  "success": true,
  "message": "update comment to: 我才是頭香啦",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "Rows matched: 1  Changed: 1  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0,
    "changedRows": 1
  }
}
```

#### 刪除某步道的評論

Response Example
```json=
{
  "success": true,
  "message": "delete comment-30",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "",
    "serverStatus": 2,
    "warningStatus": 0
  }
}
```

#### 取得所有已刪除步道
Response Example
```json=
{
  "success": true,
  "message": "get all deleted trails",
  "data": [
    {
      "trail_id": 127,
      "author_id": 1,
      "title": "測測測試",
      "description": "敘述術述",
      "location": "新竹縣埔埔鄉",
      "coordinate": {
        "x": 5,
        "y": 6
      },
      "altitude": 5,
      "length": 88,
      "season": "haru",
      "difficulty": "困難",
      "cover_picture_url": "uurl",
      "map_picture_url": "maap",
      "required_time": "ttimee",
      "rating": null,
      "situation": "wuwu",
      "gpx_url": null,
      "views": 0,
      "is_deleted": 1,
      "updated_at": "2021-10-14T06:00:27.000Z",
      "created_at": "2021-10-03T23:01:45.000Z"
    }
  ]
}
```
#### 恢復某已刪除的步道

Response Example
```json=
{
  "success": true,
  "message": "recover trail-127",
  "data": {
    "fieldCount": 0,
    "affectedRows": 1,
    "insertId": 0,
    "info": "Rows matched: 1  Changed: 1  Warnings: 0",
    "serverStatus": 2,
    "warningStatus": 0,
    "changedRows": 0
  }
}
```