Let's Eat API Documentation
===

## Overview

這個 API 規格有盡量遵守 [`REST API`](https://en.wikipedia.org/wiki/Representational_state_transfer) 的規則。每個 URL 資源都是一個名詞，例如 `user` 就是除存有關使用者的資料。這些資源可以透過 [`http methods`](https://tools.ietf.org/html/rfc7231#section-4) 來做存取，例如用 `get` 取得資料，`post` 新增資料。有些資源屬於關聯式資料，例如朋友關係，這些關聯被設計成獨立資源，一樣是透過 `http method` 存取。

這份文件可以幫助你了解這份 API 的設計架構，指示不同操作應該要使用哪些 API，詳細的 API 參數規格請參考 [這份文件](https://www.csie.ntu.edu.tw/~b09902102/swagger-ui/)

## 資源

這份 API 目前有以下資源:

- User: 使用者
- Event: 吃飯團
- Member: 吃飯團成員 (User <-> Event)
- Whitelist 吃飯團白名單 (User <-> Event)
- Blacklist 吃飯團黑名單 (User <-> Event)
- Invitation 吃飯團邀請 (User <-> Event)
- Request 吃飯團申請 (User <-> Event)
- Friend 好友名單 (User <-> User)

## Use Cases

列出一些例子，展示這些功能要如何透過這份 API 實現。

### 建立使用者帳號

使用者資源是 `User`，建立的動作是 `post`，因此要建立使用者就是

`POST: /users`

### 建立吃飯團

同理

`POST: /events`

### 加好友

目前設計好友是單向的 follower follwee 關係，同樣使用 `post` 建立

`POST: /friends`

### 邀請好友加入吃飯團

首先可能需要列出所有好友，取得資料使用 `get`，因為是找出所有 「好友」 資料

`GET: /friends`

然後在對想要邀請的人建立邀請關係

`POST: /invitation`

> `whitelist`, `blacklist`, `request` 也是相同概念

### 同意吃飯邀請

把吃飯邀請的狀態改成 `accept`，是使用 `PUT` 修改，因為是修改特定的邀請，所以是對要改的 ID 的資源修改。

`PUT: /invitations/{invitationID}`

接著後端會把該邀請對應到的使用者與對應的吃飯團建立成員關係。

> 這邊設計上會對 member 產生副作用，不確定是不是好的設計，或是如何修改

### 踢出吃飯團

要踢出吃飯團就是刪除成員關係，使用 `delete` 刪除，要對關係的 ID 操作

`DELTE: /members/{memberID}`

### 搜尋附近的好友吃飯團

`GET: /events`

解釋可能會用到的參數：

- limit: 取得資料數量
- offset: 取得資料位置（從哪裡開始）
- position: 搜尋中心座標
- distanceKM: 搜尋半徑
- friendsOf: 限定朋友

## Contribution

### 加入 github organization:

在下面填寫 email:

- abc@xy.z

### 問問題

如果有任何功能不確定要如何透過這份 API 實現，可以幫忙問問題，格式如下：

#### 如何拒絕邀請

by: ToMmyDong
詳細說明： 不能更詳細了
回覆:

`PUT /invitations/{invitationID}` 然後把 state 設成 decline

#### 如何在吃飯群傳訊息

by: ToMmyDong
詳細說明： 不能更詳細了
回覆:

目前沒有這個功能，之後會考慮加入