---
# System prepended metadata

title: API相關規範
tags: [API, 規範]

---

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需要有固定格式包起來嗎？



* 格式
```jsonld=
{
    "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資料型態


> 單一資料型態
```jsonld=
{
    "id": 1,
    "customerName": "test",
    "customerAge": 1,
    "customerBirthday": null,
}
```

> List資料型態(response)
```jsonld=
{
    "search": {
        
    },
    "sort": {
        "startData": "Asc",
        "age": "Desc",
        "createAt": "None"
    },
    "pagination": {
        "totalCount": 100,
        "perPage": 10,
        "currentPage": 1
    },
    "data": []
}
```

> List資料型態(request)
```jsonld=
// 當有分頁
{
    "search": {
        
    },
    "sort": {
        "startData": "Asc",
        "age": "Desc",
        "createAt": "None"
    },
    "pagination": {
        "perPage": 10,
        "currentPage": 1
    }
}

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

```
