# 後端API設計規範

API設計規範說明
以 `REST` 概念為主、`RPC` 為輔。
操作和運算 operate 類型的可用 RPC 概念來設計，詳細可參考 Web APIs 設計

## 1. URI 規範
參照REST基本規範

| 動詞 | 路徑 | 行為 |
| ------------ | ------------ | ------------ |
| GET | /photo | 取得多筆資料 |
| POST | /photo | 建立資料 |
| GET | /photo/{photoId} | 取得1筆資料 |
| PUT | /photo/{photoId} | 更改1筆資料 |
| DELETE | /photo/{photoId} | 刪除1筆資料 |

- 必須為小駝峰方式命名URL路徑

## 2. Header 規範
| 欄位名稱 | 說明 | 範例 | 備註|
| ------------ | ------------ | ------------ | ------------ |
| Accept-Language | 語系 | zh-cn, en-us, th-th | |
| Authorization | 權限驗證 Token | Bearer `<token>` | |
| Client-ID | 識別ID| 3fdshu2352qw458yr8y | 由後端提供 |
| System-Code | 系統市場代碼 | A:馬來 B:中國 C:泰國 | |
| Product-ID | 館別代碼 | DAL_SilkStoneAchieve | 獨立站使用 |

> 跨網域請求非認可的 Header欄位, 會造成瀏覽器會自動發出 OPTIONS 確認, 才會發出正確的 Method, 請求時間會額外消耗在 OPTIONS 階段。
`在後端 額外設定允許的表頭` http://johnzhang.io/options-request-in-express
res.header('Access-Control-Allow-Headers', 'Authorization, System-Code, Client-IP, Product-ID);

## 3. Response 規範

- Response Data 必須為 小陀峰命名規則 並且為 json type
- Http Status 必須正確回應 200, 401, 403, 500 , 503
- 任何 Request 都需回傳

| 欄位名稱 | 型別 | 說明 | 範例 |
| ------------ | ------------ | ------------ | -------|
| statusType | string | 判斷Client發出的Request驗證結果 | success: 驗證成功, error: 驗證失敗 |
| statusCode | number | 工程方便除錯使用代碼 或 不同錯誤類型前端會拿來做判斷要做什麼畫面回饋 | 未定義 |
| message | string | 定義成功失敗等等訊息 (需多語系) | 儲存成功 |
| formMessage | object | 定義表單各別欄位的錯誤訊息 | {column: ‘欄位名稱’,message: ‘回饋訊息’} |
| data | object | 前端取用的資料 | {rows: {name: imagine} } |
| newMemberToken | string | 後端判斷Token過期, 並且在可刷新時間內, 則將新token自動發行夾帶回傳 | JWT字串(不含Bearer) |

Q1. 如果表單送出到後端API, 但因某個欄位驗證失敗, 那 statusType 應該傳 success 還是 error
> Ans: 要傳 error, 但 http status 還是 200, 這個 statusType 是驗證類別

Q2. 為什麼 data 裡面需要放置一個 rows, 不直接放置資料就好
> Ans: 當前端需要取得「多筆資料」的時候, 我不希望把 data 型別從 object 改成 array, 所以固定透過一個 rows 的 array{ object } 型態的欄位, 來固定取得這種 `主要的多筆資料`, 若我需要額外的資料則可放在 data 跟 rows 同層 (例如 page, limit)

## 修訂
- 20181130 刪除 Client-IP, 因為 proxy 後的 使用者IP, 後端已經有解
- 20180717 原本有 rows 取多筆, row 取單筆, 現在取消 row 這個固定使用欄位 (感覺沒必要)

## 參考連結
- [Web APIs 設計](https://ihower.tw/cs/web-apis.html#sec1)
- [保持SOLID的單一職責原則(SRP)](https://dotblogs.com.tw/givemin5/2016/05/01/022744)
- [Http狀態碼](https://developer.mozilla.org/zh-TW/docs/Web/HTTP/Status)