前言

簡單來說，今天來講寫 API 這件事。

時至今日大家對於開 API 總會直接聯想到 HTTP 接口，酷炫一點的想到 gRPC，但其實古早時代並不是只有這兩個選項。實在是因為前後端這幾年的快速演進及微服務的興起才讓他推上這波高峰。

那古早時代到底是怎麼寫 API 的咧，其實不一定多古早，只是情境可能不一定每個人遇的到，這邊講一講我遇過的好了。

一個當然是函式庫的方式， .jar 檔給別人引入，通常核心函式庫很常這樣做。另外像是開源的函式庫也是這樣，這還有延伸問題是函式庫相依，不過這我們今天不討論。

另外還有一個 RMI (Remote Method Invoke)，遠程方法調用，聽起來就很白話。就是幫你的 local method 加上網路層可以遠端呼叫，算是 Java 實作 RPC (Remote Process Call) 的一個方法。

進階的像是 Akka 那種 message 當 method invoke 的風格，或是 socket 接收命令的這種作法，今天都不再我們的討論範圍 (那你講那麼多屁話是想被毆飛嗎？)

哈哈，開頭讓我廢話一下嘛，我們今天要講的主題還是主流為主，就是 REST & HTTP 啦 (還是有人想聽其他的，我不信 XD)

REST (Representational State Transfer) & HTTP (HyperText Transfer Protocol)

我們這邊會以 HTTP 為主，但請注意 REST 並不是專指 HTTP 喔。這短短的四個英文字母厲害的點是因為現在有太多東西基植於它，一般的後端、SOAP (Simple Object Access Protocol)、支持 REST 的資料庫 (Elasticsearch)、HTML。

第一個重點是 HTTP 是一個資源跟方法組合起來的的協定，它把你需要的東西當成資源，所以通常是複數名詞，動名詞也算。配上常見的 HTTP 動詞，GET、POST、PUT、DELETE、PATCH、OPTIONS，來構成 API 的定義。

第二個重點是 Stateless，不過請不要誤解，無狀態不是說你的後端要無狀態，是說這個協定本身在呼叫的時候每一次之間是無關連的，你這次要呼叫的時候應該跟上次呼叫沒相干。

那我們就直接進範例，以使用者這個例子來看 CRUD 四大操作。

GET, http://localhost/api/v1/users/254, 查詢 id=254 的使用者
後面如果不帶 id，就是查整個 collections，作法就會很豐富，一般還會多帶一些 QueryString 來做，例如 ?page=1&size=10&sort=age,desc，意思是第一頁、一頁十筆資料、以 age 遞減排序

POST, http://localhost/api/v1/users, 新增使用者，id 不給，通常由後端生成
{
  "id":0,
  "name":"Daniel",
  "age":24
}

PUT, http://localhost/api/v1/users, 覆蓋 id=25 的使用者，是整個蓋掉。雖說如此現在很多都會實作 PUT 部分更新，所以就不太實作 PATCH 了
{
  "id":25,
  "name":"Daniel",
  "age":23
}

DELETE, http://localhost/api/v1/users/255, 刪除 id=255 的使用者

PATCH, http://localhost/api/v1/users, 部分更新 id=25 的使用者欄位
{
  "id":25,
  "age":21
}

OPTIONS, http://localhost/api/v1/users, 用來查詢這個 endpoint 有什麼 method 可以用，另外在跨域請求時，也會先發 OPTIONS 來確認是否接受跨域請求

另外有關 HTTP 回應碼的部份，我想 WIKI 說的很清楚，我這邊不多加贅述。

另外我們來提 idempotent 這件事，在文件中是有提及 GET、HEAD、OPTIONS、TRACE、PUT、DELETE 為 idempotent。HTTP Idempotent Methods 定義是如果 client 發出多次同樣的請求，對 server 的影響不變，則此方法為 Idempotent Methods。也就是說同樣的請求不小心送了多次，也不用擔心對 server 造成不同的影響。

另外如果你注意到我的 path 中有版號，這算是一個向下相容的好習慣，當你要進行破壞性升版的時候，請保留舊的接口。這樣可以避免別的部門或是客戶來追殺你，真心推薦R。

About Me

Jian-Min Huang

wide range skill set backend engineer

Research, Architecture, Coding, DB, Ops, Infra.

mainly write Java but also ❤️ Scala, Kotlin and Go

http://github.jianminhuang.cc

http://linkedin.jianminhuang.cc

http://note.jianminhuang.cc

yfr.huang@hotmail.com