API相關規範
===
###### tags: `API` `規範`

## 問題

### 不同的手機是否可以登入同一個OCP帳號？
* 不行！
* 跟老闆確定！

### 要合併次特店的網站qrcode合併到biz，變成同一個網址

### 當外部的公司要如何界接我們的系統
exp: 請款單, PayPage
* 當需要實做的時後再說....

### 走API的模式，是否要透過TOKEN做驗證？
* 目前無法確定是那個系統來產生TOKEN
* 暫訂OCP
* 是否以oAuth概念實做？
* 確認老闆的想法
* 後台
* 目前確認要做資料移轉的系統，到最後會是統一用OCP登入
* 可以包含以下
* TPM([NFT](https://nft-saas-ui.staging.nftbox.me/zh) SDK看起來可以幫我們實做這一塊)
* MFA
* Fido
* 消費者
* TPM
* 生物辨識
* 速度上如何克服？

### Response需要有固定格式包起來嗎？

* 格式

{
    "code": "string",
    "dateTime": "string",
    "msg": "string",
    "exp": "string",
    "data": {} | []
}

* Code可以定義相關規範嗎？
* 可以，但各個服務需各自定義自己的Code的對應表
* A0000 處理成功

### I18N相關規範以及如何實做？
#### 流程：
* 您總共花了:amount元
* Android:
* <string name="forbidden_permissions">No tiene permiso %s</string>

* 開一個GIT i18n的專案
* 要確定每個服務要打包至的位置暫訂FTP
* 從固定的翻譯檔到各個語言的翻譯程式是由noon大大來實做
* 每個語言或者服務都要確定自己的翻譯檔案相關的格式，請當回家功課
* 當個別專案要push的時後，要記得再做一次i18n的更新

### 外連內的流程？

### Client To Server 加密格式？

### 上傳檔案的部分該如何實做？
> 可參考GOOGLE檔案上傳下載功能 [參考文件](https://support.google.com/docs/answer/10519333?hl=zh-Hant)
* 檔案上傳是否能只有一個API?
* 可以，具體實做下次討論

* 新增檔案上傳的格式
- [ ] form body - post
- [ ] base64
* 上傳檔案後的回應？
- [ ] 連結
* 上傳下載需要加密？
* 修改？
* 刪除？

## 規範

### 共識

# Server To Server 需要統一Request Response規格嗎？
* 照舊，需要補齊相關文件

### Client To Server 是否要加密？
* 需要

### 在複合資料下，會偏向多次請求API組合複合資料，還是獨立API取得？
* 兩種方式都會存在，但以多次請求API組合複合資料為首要方向

### 未來有可能會有Server Side Render嗎？
> 如果是透過SSR的話，取得List資料就需要先取得"**分頁**"&"**排序**"&"**搜尋**"相關資料。
* 是的，未來要是有SSR，Server Side會將"**分頁**"&"**排序**"&"**搜尋**"相關資料Response出來。

### 輸入輸出
* API相關的實做規範請盡可能遵循RESTful精神，相關精神包含：
* 盡可能使用Http Status Code，以下為常見的Http Status Code：
* 200 OK - 請求成功完成並返回請求的資源。
* 201 Created - 在伺服器上成功建立新資源。
* 204 No Content - 請求成功完成，但不需要返回任何內容（例如，用於 DELETE 請求）。
* 400 Bad Request - 請求參數不正確或缺少必要的參數。
* 401 Unauthorized - 請求需要身份驗證，但提供的憑證無效。
* 403 Forbidden - 請求被伺服器拒絕，通常是因為請求者沒有訪問所請求資源的權限。
* 404 Not Found - 請求的資源不存在。
* 405 Method Not Allowed - 請求使用了伺服器不支持的 HTTP 方法。
* 409 Conflict - 請求衝突，通常是因為資源已經存在。
* 500 Internal Server Error - 伺服器遇到了一個意外的錯誤，無法完成請求。
* 盡可能將資源以CRUD做規劃
* 資料的傳輸，請以JSON格式傳輸，JSON規格請參考[ECMA-404](https://www.ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf)，範圍包含：
* GET
* Response Body
* POST
* Request Body
* Response Body
* PUT
* Request Body
* 小駱峰命名，範圍包含：
* URL Path param
* GET
* URL Query
* Response Body JSON
* POST
* URL Query
* Request Body JSON
* Response Body JSON
* PUT
* URL Query
* Request Body JSON
* Response Body JSON
* DELETE
* URL Query
* 請合理使用null，而不是透過預設值當作空資料，何時使用null何時使用預設資料，該部分可以透過討論再來做定義
* 未來要是有非必填的型態，將以當下型態以及null做欄位型態
* 資料型態將劃分為以下兩種規格：
* 單一資料型態
* List資料型態

> 單一資料型態

{
    "id": 1,
    "customerName": "test",
    "customerAge": 1,
    "customerBirthday": null,
}

> List資料型態(response)

{
    "search": {
        
    },
    "sort": {
        "startData": "Asc",
        "age": "Desc",
        "createAt": "None"
    },
    "pagination": {
        "totalCount": 100,
        "perPage": 10,
        "currentPage": 1
    },
    "data": []
}

> List資料型態(request)

// 當有分頁
{
    "search": {
        
    },
    "sort": {
        "startData": "Asc",
        "age": "Desc",
        "createAt": "None"
    },
    "pagination": {
        "perPage": 10,
        "currentPage": 1
    }
}

// 當有"沒有"分頁
{
    "search": {
        
    },
    "sort": {
        "startData": "Asc",
        "age": "Desc",
        "createAt": "None"
    },
    "pagination": {}
}