7個好的API應該有的設計

1. Use clear naming

例如:

http://example.com/api/v1/carts/123

而不要

http://example.com/api/v1/cart/123

因為是一個集合的資料，而不是單個，這樣比較合乎邏輯

2. Ensure reliability through idempotent API

無論執行多少次相同操作都要產生相同結果，避免問題產生

GET、PUT、DELETE都具有indempotence特性，請求多少次都是相同結果
POST、PATCH不具有indempotence特性，會一直新增，不過PATCH可以以indempotent的方式發出請求

3. Add versioning

例如:

http://example.com/api/v1/carts/123

變成

http://example.com/api/v2/carts/123

由此一來當API需要改版時，不會影響到舊有的用戶

4. Add pagination

當資料量龐大時無需全部載入即可顯示，減輕API的流量壓力

兩種方式:

1. Page + Offset: 當資料量大的時候會有點慢，因為要從頭開始數，直到請求的那頁
2. Cursor-based:指針方式，指向特定資料，下一頁的時候就無需從頭尋訪，通常經過加密

參考:

#筆記 常見分頁 API 使用介紹：Offset & Cursor — SwiftUI 新手入門 6-9

龐大資料庫分頁方案 Cursor-based pagination

5. Use clear query strings for sorting and filtering API data

例如:

GET /users?sort_by=registered

或

GET /users?filter=color:blue

或合起來

GET /users?sort_by=registered&filter=color:blue

好處是API在接收請求的時候就可以直接向資料庫請求特定數據，需要加更多條件的時候也可以直接接在最後面無需從頭來過，甚至還可以將結果cache，提升速度

6. Don’t make security an afterthought when designing APIs

例如API key，放在header容易遭竊，因此需要全程TLS加密，每個請求都要驗證以保證安全

7. Keep cross-resource references simple

url越清楚越好

例如:

http://example.com/api/v1/carts/123/items/321

而不要

http://example.com/api/v1/items?card_id=123&item_id=321

最後

別忘了限制請求量