# Ch 01. Web API 設計要素

:::success
**API 從被設計出來的那刻開始，要以他會是永存且不會消失的來看待**
:::

當一支 API 被廣泛使用後，會很難做大幅度的修改，否則因容易影響到不同的使用者而停擺；而如果 API 設計的草率，則後續維護時可能會發現當初的設計無法被復用，但又因為已經交由使用者使用，而無法輕易修改。

因此在產品規劃階段，就需要重視 API 的設計。

> 一個系統或服務的架構是由各式各樣的設計來組成的，一系列的設計決策會塑造出系統的表現形式及功能。

企業對外開放的 API 代表了企業想傳達的價值，而 API 的特性會表達出該企業在設計系統時所重視的特點

## **Web API 的設計要素**

* 商業能力
* 產品思維
* 開發體驗

### 商業能力

:::info
企業 ***為了獲利或維持市場競爭力的能力***，可以是組織對外或對內所展現出來的能力
對外主要是吸引消費者上門的能力，對內則是對於內部資源的整合等等
:::

三種用來輔助提高自身商業能力的方法：
* 企業自己宣傳
* 外包廠商代為宣傳
* 兩者混和使用

可以將服務內的部分功能交由外包廠商提供，企業就可以專注在強化自己的商業能力，讓自己有更多的心力去作出市場的差異化並提高自己的商業能力

API 可視為數位化後的商業能力，每支 API 都會帶來不同的商業能力

### 產品思維

在 Web API 不成熟的時代，企業間已經有資訊整合的能力，但多是以客製化的方式進行；因此每多服務一個客戶都是一次重複的資源損失，資源無法共享

企業提供的 API 應該要專注在本身所能帶給客戶的價值，讓客戶自行根據 API 的功能去實現他想展現的**商業能力**

:::info
產品化代表減少客製化，API 提供統一標準給所有客戶，在設計階段就納入客戶意見，就能更貼近市場需求，就有機會贏來更多潛在用戶
:::

### 開發者體驗

:::info
用戶體驗 (User Experience, UX) 主要是聚焦在如何滿足客戶使用感受，開發者體驗 (Developer Experience, DX) 是聚焦在提升開發者使用 API 時的體驗
:::

一個好的 API 可以讓開發者更快速簡單的上手，讓他們可以更專心在發展自己的**商業能力**上，甚至讓開發者也願意去推廣給其他人使用；而不好的文件會增加開發者的溝通成本，因此好的文件也可以幫助改善開發者體驗

:::success
API 不對外開放的公司可能會沒什麼感覺，因為對內部的開發者來說，API 做再爛都還是要串，沒討價還價的能力；但如果 API 的受眾是外部使用者，設計不良的 API 就有可能會影響到客戶的使用意願
:::

## **API 設計 = 溝通與交流**

API 的溝通不只是團隊內的溝通，而是對內對外都有，跟不同對象的溝通可以讓我們從不同的角度去設計 API，進而實現貼近市場需求的 API

溝通可以分為3個面向：
* 網路面的溝通 (通訊協定)
* 開發者面的溝通 (需求探索)
* 市場面的溝通 (價值)

### 網路面的溝通

不同的通訊協議會影響 API 的使用場景，因此需要根據 API 的功能或會面對到的效能問題也列入考慮，才能決定出適合的通訊協議

### 開發者面的溝通

在 API 的需求探索及設計階段盡早納入來自開發者的意見，才能實現貼近他們真正需求的 API 設計

### 市場面的溝通

提供開發者 API 所能帶來的價值，以及能幫助他們實現那些目的，使得客戶能使用 API 來實現各自所需的商業價值

## **檢視軟體設計原則**

軟體設計關注的是程式碼的組成架構與通訊，API 設計的基礎原則也是來自軟體設計，但 API 的交流對象更廣泛，不只公司內部的開發者，也包含外部的開發者

* 模組化
* 封裝
* 高內聚低耦合

### 模組化

模組是軟體中的最小單元，由類別、方法等等所構成，也被稱為元件或函式庫；在 Web API 中是用來劃分不同 API 的功能，每支 API 會有分明的功能差異

### 封裝

用於隱藏元件的內部實作細節，在 Web API 來說是指使用者只需要知道如何調用 Web API 而不需要知道內部的實作細節

### 高內聚低耦合

高內聚是一個模組的程式碼只與該模組有相關，而不與其他模組的程式碼相關；低耦合是兩個模組間的程式碼彼此不高度依賴，只透過公開出來的 API 進行溝通

在 Web API 上會將相關度高的 API 集合起來，產生一個服務，並且不會讓外部知道該服務內的 API 是如何調用其他的 API

## **Resource-Based (以資源為基礎的) API 設計**

:::warning
Data Service 需要注意的東西
:::

### 資源 != DB 模型 / 物件模型 / 領域模型

API 所代表的資源及對外丟出去的 Response，不該跟資料庫的資料結構一樣，如果 Response 跟 DB 一樣的話，後續改資料結構或替換 DB 時容易導致 Response 一起受到影響。DB 的資料結構的確可能會影響 API 的資料格式，但 Response 應該始終保持 API 所想表達的意義

也包含了程式碼內部在使用的物件模型或領域模型，跟 DB 模型的問題一樣，應該要盡量避免實作細節或業務細節，指專注在資訊的交換上

* 程式連帶受到影響
DB 改了需要從最底層一路改到外部的 Response
* 冗餘的互動
因為一支 API 只能取的一張表的資料，所以要透過多次 API 的往來才能組出複雜查詢的結果
* 資料不一致
因為每次 API 查詢的時間會有些微落差，所以可能會產生資料不一致的問題 (Dirty Read)
* 資料表的資料對外部使用者來說語意不明
資料表的資料可能是經過設計，可以幫助查詢等等的，但對於使用者來說，可能不好閱讀
* 機敏資料外洩
如果沒注意到，可能不小心就把機敏資料跟著一起洩漏了

### Web API 設計原則

1. 設計 API 需要大家一起討論，而不是獨自一人做
2. API 設計是目標導向的，聚焦在目標並確保是有價值的
3. 沒有最好的 API 只有最適合需求的 API
4. API 文件很重要
5. 已做完的 API 不會輕易消失，仔細規劃，後續迭代改進，才能讓 API 穩定又有彈性

###### tags: `Web API 設計原則：API與微服務傳遞價值之道` `Book`