--- 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)