Wednesday, November 16, 2016

Restful API design

在公司最近進行的項目,是 API 的設計。網路上已經有許多 Restful API best practice 的文章了。所以這邊我寫的是個人親手踩過的坑。

(1) Gzip compression support
http 要支援 Gzip 的話,在公司的架構算是一件容易的事,因為真實的 API server 前,還有一台 nginx 在做 reverse proxy 。所以,只需要設定 nginx ,讓 nginx 可以做 gzip 就可以了。並不需要從 API server 的源頭端改下去。
gzip on;
gzip_types    application/json;


(2) 送出的資料量如果大的話,要記得做 pagination 。最好的作法應該使用定義於 RFC 5988 的 Link header ,因為這樣子就不必將 link header 的資訊放在 body 裡頭。

(3) 如果 API 的參數有時間的參數,考慮使用 Unix time 格式或是 ISO-8601。Unix time 是我本來就知道的。 ISO-8601 也是標準格式,我則是查了一段時間才搞懂。










後記:
讀過了 Restful API best practices 之後,我認為其中最重要的精神應該還是不要重造輪子。能利用 http 既有 header 來做的功能,就儘量利用 http 來做。如此才可以將複雜度(complexity)隱藏在 http 傳輸協定裡。比方說:
1  資料壓縮                   → http 的 header  => Accept-Encoding: gzip
2  認証                           → http digest authentication
3  合理使用量               → http rate limit
4  分頁(pagination)        → http link header
5  加密                           → https
6  CRUD 不同的操作   → http method : put, delete, get, post
7  caching                       → ETag, Last-Modified
8  exception handling     →  http status code