---
# System prepended metadata

title: 更改 API 以符合 RESTful 的格式
tags: [v2]

---

---
title: 更改 API 以符合 RESTful 的格式
tags: v2
---
[ToC]

# 更改 API 以符合 RESTful 的格式

## FiO API url 最終規範

- `/api/v2[/projects/:project_id]/{moduleName a.k.a. resourceName}[/{resourceName}]/:resource_id`
- `/api/v2[/projects/:project_id]/moduleName/resourceName/:resource_id`

### 兩個字以上組成請用 hyphen 隔開

### 同一種資源不同動作請在前面加入 `actions` 當作 resourceName

## 範例說明
1. 如果 moduleName 跟 resourceName 概念一樣
    - 錯誤 Example: `/api/v2/orders/orders/:order_id`
    - 正確 Example: `/api/v2/orders/:order_id`
2. 如果 moduleName 跟 resourceName 概念不一樣
    - Example: `/api/v2/projects/:project_id/nft/tokens/:token_id`
3. 同一種資源不同動作
    - Example: `/api/v2/payments/:payment_id/actions/:pay-by-prime`
    - Example: `/api/v2/payments/:payment_id/actions/:pay-by-token` 

## 目標
- 將 FiO 的 API url 都改成符合 RESTful api 的格式
- 先處理 v2 api

## 注意事項
- 要注意是否有客戶正在使用 API
- 改 API url 也要改 ACL
- 是否要連 model 一起改? 
- 檔案內的路徑也要更改?
- 前端也要更動

## 作法
- 同時保有更改前後的 API，之後再逐步廢棄更改前的 API
- 將要廢棄的檔案放進 deprecated 資料夾，以利之後分辨哪些是要廢棄的

## 問題
Q: 更改 url 是否會影響到功能?
Ans: 有些 API url 在經過調整後，接收的參數可能會不一樣，但是不會影響到功能
此張卡片要解決的是 API url 命名問題，要調整功能的話要再另開卡片處理

## FiO v2 API
- v 代表符合，不做更動
- x 代表是不對外開放的
- o 代表更動 API url 後， API 裡的程式碼也需要調整
- f 代表會影響到前端

| check | moduleName       | Method | API                                                             | 預計更改後 API                                               | 備註    |
| ----- | ---------------- | ------ | --------------------------------------------------------------- | ------------------------------------------------------------ | --- |
|       | OPEASEA          | GET    | `/api/v2/opensea/:contract_address/:token_id`                   | `/api/v2/opensea/addresses/:contract_address/tokens/:token_id` |     |
|       | EVM_RECEIPT_HOOK | POST   | `/api/v2/evm-receipt-hook/on-chain`                             | `/api/v2/evm-receipt-hook/on-chain-data`                     | 這邊不對外開放，暫時不更改 |
|       | EVM_RECEIPT_HOOK | POST   | `/api/v2/evm-receipt-hook/nft`                                  | `/api/v2/evm-receipt-hook/nft`                               |     |
| x     | MIGRATE          | GET    | `/api/v2/migrate`                                               |                                                              |     |
| x     | MIGRATE          | GET    | `/api/v2/migrate/delete-unused-v2-api-key`                      |                                                              |     |
| x     | MIGRATE          | GET    | `/api/v2/migrate/ipfs-storage`                                  |                                                              |     |
|       | PROJECT          | GET    | `/api/v2/project`                                               | `/api/v2/projects`                                           |     |
|       | PROJECT          | POST   | `/api/v2/project`                                               | `/api/v2/projects`                                           |     |
|       | ON_CHAIN         | POST   | `/api/v2/on-chain/:project_id`                                  | `/api/v2/projects/:project_id/on-chain-data/blockchains/${chainName}/networks/${chainType}` |     |
|       | ON_CHAIN         | GET    | `/api/v2/on-chain/:project_id`                                  | `/api/v2/projects/:project_id/on-chain-data`                 |     |
|       | ON_CHAIN         | GET    | `/api/v2/on-chain/:project_id/:data_id`                         | `/api/v2/projects/:project_id/on-chain-data/:data_id`        |     |
|   f   | NFT              | GET    | `/api/v2/nft/products`                                          | `/api/v2/products`                                           |     |
|   f   | NFT              | GET    | `/api/v2/nft/:project_id`                                       | `/api/v2/products/:project_id`                               |     |
| o f   | NFT              | GET    | `/api/v2/nft/:project_id/orders/:order_id/checkout`             | `/api/v2/orders/:order_id?type=checkout`                          | 這以後應該要廢棄，這裡使用的 order_id 是以前流水號的 order_Id，以後應用 Object_id 的 order_id 取代 |
| o f   | NFT              | GET    | `/api/v2/nft/:project_id/orders/:order_id/status`               | `/api/v2/orders/:order_id?type=status`                            | 這以後應該要廢棄，這裡使用的 order_id 是以前流水號的 order_Id，以後應用 Object_id 的 order_id 取代 |
|   f   | NFT              | POST   | `/api/v2/nft/:project_id/tokens/draft`                          | `/api/v2/projects/:project_id/nft/tokens/draft`              |     |
|   f   | NFT              | POST   | `/api/v2/nft/:project_id/tokens/:token_id/mint`                 | `/api/v2/projects/:project_id/nft/tokens/:token_id/mint`     |     |
|       | NFT              | GET    | `/api/v2/nft/project_id/tokens/:token_id/owner`                 | `/api/v2/projects/project_id/nft/tokens/:token_id/owner`     |     |
|       | IPFS             | POST   | `/api/v2/ipfs/:project_id/bucket`                               | `/api/v2/projects/:project_id/ipfs/buckets`                  |     |
|       | IPFS             | POST   | `/api/v2/ipfs/:project_id/upload`                               | `/api/v2/projects/:project_id/ipfs/files`                    |     |
|       | IPFS             | GET    | `/api/v2/ipfs/:project_id/:bucket_id/:cid`                      | `/api/v2/projects/:project_id/ipfs/buckets/:bucket_id/cid/:cid`  |     |
|       | PAYMENT          | POST   | `/api/v2/payment/:payment_id/tappay/checkout/pay-by-prime`      | `/api/v2/payments/:payment_id/actions/pay-by-prime`           |     |
| f     | PAYMENT          | POST   | `/api/v2/payment/tappay/orders/:order_id/checkout/pay-by-prime` | `/api/v2/orders/:order_id/actions/pay-by-prime`               | 這以後應該要廢棄，這裡使用的 order_id 是以前流水號的 order_Id，以後應用新的 Object_id 的 order_id 取代 |
|       | PAYMENT          | POST   | `/api/v2/payment/tappay/orders/:order_id/checkout/pay-by-token` | `/api/v2/orders/:order_id/actions/pay-by-token`               | 這以後應該要廢棄，這裡使用的 order_id 是以前流水號的 order_Id，以後應用新的 Object_id 的 order_id 取代 |
| f     | OPENCERTS        | POST   | `/api/v2/opencerts/:project_id/upload`                          | `/api/v2/opencerts/projects/:project_id/files`               | 內部測試用，不用更改 |
| f     | OPENCERTS        | POST   | `/api/v2/opencerts/:project_id/issue`                           | `/api/v2/opencerts/projects/:project_id/issue`               | 內部測試用，不用更改 |
| v     | WALLET           | POST   | `/api/v2/wallets`                                                |                                                              |     |
| v     | WALLET           | GET    | `/api/v2/wallets`                                               |                                                              |     |
| v     | WALLET           | PUT    | `/api/v2/wallet/:wallet_id`                                     |                                                              |     |
| v     | WALLET           | DELETE | `/api/v2/wallets/:wallet_id`                                    |                                                              |     |
| v     | GENERAL-ROLES    | POST   | `/api/v2/acl/general-roles/admin`                               |                                                              |     |
| v     | GENERAL-ROLES    | DELETE | `/api/v2/acl/general-roles/admin`                               |                                                              |     |


## 預計做法

### 共通
- 將所有 project 都改成 projects
- 將帶有 project_id 前面都加上 projects

### on-chain
#### 將鏈的名稱寫進 url 裡？
- alchemy 作法
    - 將 blockchain and network 直接寫在 domain name
    - `https://eth-mainnet.alchemyapi.io/nft/v2/${apiKey}/getNFTMetadata`
    - `https://polygon-mumbai.g.alchemy.com/v2/${apiKey}`
- Crypto APIs
    - 將 blockchain and network，寫在 API url 資源後面
    - GET `/blockchain-data/{blockchain}/{network}/addresses/{address}`
    - [參考](https://developers.cryptoapis.io/technical-documentation/api/blockchain-data/unified-endpoints/get-address-details)
> 上述兩種都是直接將鏈的名稱跟網路寫在 API url 裡，很直覺

#### 結論
- 把 chain name and network 寫進 API url
- 資源名稱改叫 on-chain-data or blockchain-data or blockchain


### 將 orders 獨立出來
- order 應不屬於任何資源底下的，應是一個獨立的資源

## 現在 order 情況
![](https://i.imgur.com/XtthFc0.jpg)
- 目前在 tms 裡 order 有新舊兩種 table 並行中，出現在 API url 的 order_id 都是屬於舊的 table
    - 舊的 table 叫: orders
    - 新的 table 叫: order
- 新的 orders 有跟 payments 連動，產生 order 即會產生 payment，會透過 payment 來付款
- tms 前端還是使用舊的 order ，也就是用舊的流水號 order_id 付款
- 未來會轉換成用 payment_id 付款，目前 artify 已經接上新的 orders 並用 payment 去付款


## 參考
- [google naming convention](https://cloud.google.com/apis/design/naming_convention)
- [訂單模組升級](https://trello.com/c/c0x14S8s/421-fio-nft-creator-v2-%E8%A8%82%E5%96%AE%E6%A8%A1%E7%B5%84%E5%8D%87%E7%B4%9A)