week 1 API 哪有那麼難

2021/7/26

API 哪有那麼難

• 撰写安全合格的REST API

• Thoughtworks洞见

• Restful API 中的错误处理

• 跟着 Github 学习 Restful HTTP API 设计

總結

第一篇講怎麼樣合格，但因為太多新單字，一直查生字很痛苦，還好有摘要。 第二篇（四大錯誤）比較簡單一點講實務上的操作，跟第一篇、第四篇講的安全性部分有關。 第三篇也偏實作，講撰寫錯誤回應。跟 status code 部分比較有關。

我覺得純閱讀我都不知道在幹嘛，看完也記不起來。 所以我幾個想了解的，查一下這東西要怎麼在Laravel上使用，先會用就好。

太難ㄌ，看完就忘。我也記不得REST要符合什麼才REST。我決定只記得以下幾點：

1. 合格的 REST AP I很難，不是只有動詞和 status code。

   1. RFC

   2. REST 等級三 - HATEOAS

2. error response、如何撰寫，可以參考 Github API。

3. 安全性

   1. Security Headers

      1. 請求限制, throttle

   2. 不小心洩漏的業務訊息/過多的訊息

4. 驗證&快取 (Header)

   1. Etag

   2. Conditional Request

合格的 REST API

• RFC一致性

  • HTTP/1.1

  • HTTP/2.0

• Methods

• Headers

  • Accept

  • If-Modified-Since/If-None-Match

  • If-Match

• Status Code

• 安全性

• 请求数据验证

  • Request headers是否合法

  • Request URI和Request body是否合法

• 数据完整性验证

  • 保证要修改的数据和服务器里的数据是一致的 —— 这是通过Etag来完成。Etag可以认为是某个资源的一个唯一的版本号。当客户端需要修改该资源时，需要通过"If-Match"头来提供这个Etag。服务器检查客户端提供的Etag是否和服务器同一资源的Etag相同，如果相同，才进行修改，否则返回412 precondition failed。

• 访问控制

• HTTPS

• 其他

  • rate limiting：访问限制

  • metrics：服务器应该收集每个请求的访问时间，到达时间，处理时间，latency

  • docs：丰富的接口文档

  • hooks/event propogation：其他系统能够比较方便地与该API集成

RESTful架构风格下的4大常见安全问题

1. API 並未檢查該請求的不同欄位資料是否具備關聯。 例如，某位使用者是否具擁有某張訂單；因此，使用者可以利用 API 讀寫並非其擁有的訂單。

2. API 並未設置重要的資安 header，包括但不限於防 iframe、防自動偵測檔案類型並執行、 防 XSS、嚴格 SSL 模式。

3. API 本身揭露了商業機密，例如顯示流水號揭露了用戶量、回傳 JSON 包括不應該包括的資料。

4. API 並未限制傳輸速率，因此容易被 DDos 攻擊。

必要的 Security Header

• X-Frame-Options: DENY 可設定不允許自己的網站被嵌入 frame

• X-Content-Type-Options: nosniff 可設定瀏覽器嚴格執行返回 content-type 格式

• X-XSS-Protection: 1; mode=block 可設定瀏覽器開啟 XSS 防禦&發生XSS要停止即將渲染的內容

• Strict-Transport-Security: max-age=31536000; includeSubDomains 在接下來的一年裡，設定瀏覽器對此網域即其子網域直接發起 HTTPS 連結

Restful API 中的错误处理

學到一些制定錯誤訊息良好點子

• 使用 http 狀態碼（建議）

  • 使用自訂的錯誤分類以提高可讀性、可維護性

• 自訂業務錯誤碼

• 提供給用戶看的錯誤訊息（建議）

• 提供給開發者的錯誤訊息

Ｑ: 討論如何撰寫好的 error response

跟着 Github 学习 Restful HTTP API 设计使用 HTTPS

• API 地址和版本

• schema

  • 主流是JSON

• 以资源为中心的 URL 设计

  • 注意資源的單複數、小寫

• 使用正确的 Method

  • 更新和创建操作应该返回最新的资源，来通知用户资源的情况；删除资源一般不会返回内容。

• Query 让查询更自由

• 分页 Pagination

  • per_page、page

  • 相关的分页信息还可以存放到 Link 头部

• 选择合适的状态码

• 错误处理：给出详细的信息

• 验证和授权

• 限流 rate limit

• Hypermedia API

• 编写优秀的文档

為什麼需要 REST API ？

在不同 Server 上的系統，需要一個統一的規格作為溝通橋樑

什麼是 REST API ？

基於 RFC 為標準來定義的資料傳遞格式

如何設計合格 REST API ？（足夠企業內部使用）

• API Spec 必須符合 RFC 標準

  • 錯誤處理：HTTP Status Code

  • HTTP Method

  • RFC3986 URI Case Sensitive url 統一使用 lowercase 避免歧義

• 安全性：對 Request 進行權限驗證

在合格 REST API 之上我們還可以針對那些細節優化 ？（規模化：開放給外部使用）

降低溝通成本

• 錯誤處理(盡可能提供更精確的錯誤訊息)：在 Response Body 帶上業務錯誤碼，降低溝通成本

• Docs: 方便系統外部的人做使用，降低溝通成本。

提升效能

• Rate Limiting: 針對訪問數量進行，防止 DDOS 攻擊，减少 Server 壓力

• Metrics: 搜集 Request 的統計數據（訪問、到達，處理時間...)，藉此了解使用者的習慣，優化 API 性能，應對突發的流量。

Integration

• Hooks/Event propagation：便於和其他系統做整合

版本控制

• API 版本號 api/v1

這篇提及 Restful API 的設計原則，可跟選文ㄧ相輔相成，幾個值得 highlight 的要點：

• rate limit 的具體實作，採用三個 headers達成 ：

  • X-RateLimit-Limit : 單位時間內同一個請求來源可發送的請求次數

  • X-RateLimit-Remaining：還可以發送的次數

  • X-RateLimit-Rest: 單位時間之到期時間

• 鼓勵將 Restful API 做到 Hypermedia (有些國外的第三方金流服務就大量使用這種 pattern 0v0)

其他

Laravel ETag and Conditional Requests

Laravel Cache Control Middleware

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/download', function () {
        // ...
    });
});

Laravel ETag and Conditionals Package

Laravel API 性能优化：使用ETag 和条件标头进行缓存 - LearnKu

ETag's and Conditional GET's in Laravel 4 - Fideloper

Lararvel Security Header

chetans9/SecureHeadersMiddleware.php

Laravel trottle

Laravel 8 的新功能：RateLimite facad

Improved Rate Limiting

https://laravel.com/docs/8.x/routing#rate-limiting

• New simple way of creating custom Rate Limiters in Laravel 8

Laravel 7

throttle middleware

Laravel 8

route provider

Laravel API throttle 原理分析