自從Roy Fielding博士在2000年他的博士論文中提出[REST](http://zh.wikipedia.org/wiki/REST)（Representational State Transfer）風格的軟件架構模式后，REST就基本上迅速取代了復雜而笨重的SOAP，成為Web API的標準了。 什么是Web API呢？ 如果我們想要獲取一篇Blog，輸入`http://localhost:9000/blog/123`，就可以看到id為`123`的Blog頁面，但這個結果是HTML頁面，它同時混合包含了Blog的數據和Blog的展示兩個部分。對于用戶來說，閱讀起來沒有問題，但是，如果機器讀取，就很難從HTML中解析出Blog的數據。 如果一個URL返回的不是HTML，而是機器能直接解析的數據，這個URL就可以看成是一個Web API。比如，讀取`http://localhost:9000/api/blogs/123`，如果能直接返回Blog的數據，那么機器就可以直接讀取。 REST就是一種設計API的模式。最常用的數據格式是JSON。由于JSON能直接被JavaScript讀取，所以，以JSON格式編寫的REST風格的API具有簡單、易讀、易用的特點。 編寫API有什么好處呢？由于API就是把Web App的功能全部封裝了，所以，通過API操作數據，可以極大地把前端和后端的代碼隔離，使得后端代碼易于測試，前端代碼編寫更簡單。 一個API也是一個URL的處理函數，我們希望能直接通過一個`@api`來把函數變成JSON格式的REST API，這樣，獲取注冊用戶可以用一個API實現如下： ~~~ @get('/api/users') def api_get_users(*, page='1'): page_index = get_page_index(page) num = yield from User.findNumber('count(id)') p = Page(num, page_index) if num == 0: return dict(page=p, users=()) users = yield from User.findAll(orderBy='created_at desc', limit=(p.offset, p.limit)) for u in users: u.passwd = '******' return dict(page=p, users=users) ~~~ 只要返回一個`dict`，后續的`response`這個`middleware`就可以把結果序列化為JSON并返回。 我們需要對Error進行處理，因此定義一個`APIError`，這種Error是指API調用時發生了邏輯錯誤（比如用戶不存在），其他的Error視為Bug，返回的錯誤代碼為`internalerror`。 客戶端調用API時，必須通過錯誤代碼來區分API調用是否成功。錯誤代碼是用來告訴調用者出錯的原因。很多API用一個整數表示錯誤碼，這種方式很難維護錯誤碼，客戶端拿到錯誤碼還需要查表得知錯誤信息。更好的方式是用字符串表示錯誤代碼，不需要看文檔也能猜到錯誤原因。 可以在瀏覽器直接測試API，例如，輸入`http://localhost:9000/api/users`，就可以看到返回的JSON：  ### 參考源碼 [day-09](https://github.com/michaelliao/awesome-python3-webapp/tree/day-09)