自從Roy Fielding博士在2000年他的博士論文中提出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實現如下：
|
1
2
3
4
5
6
7
8
|
@api@get('/api/users')def api_get_users(): users = User.find_by('order by created_at desc') # 把用戶的口令隱藏掉: for u in users: u.password = '******' return dict(users=users) |
所以，@api這個decorator只要編寫好了，就可以把任意的URL處理函數變成API調用。
新建一個apis.py，編寫@api負責把函數的返回結果序列化為JSON：
|
1
2
3
4
5
6
7
8
9
10
11
12
|
def api(func): @functools.wraps(func) def _wrapper(*args, **kw): try: r = json.dumps(func(*args, **kw)) except APIError, e: r = json.dumps(dict(error=e.error, data=e.data, message=e.message)) except Exception, e: r = json.dumps(dict(error='internalerror', data=e.__class__.__name__, message=e.message)) ctx.response.content_type = 'application/json' return r return _wrapper |
@api需要對Error進行處理。我們定義一個APIError，這種Error是指API調用時發生了邏輯錯誤（比如用戶不存在），其他的Error視為Bug，返回的錯誤代碼為internalerror。
客戶端調用API時，必須通過錯誤代碼來區分API調用是否成功。錯誤代碼是用來告訴調用者出錯的原因。很多API用一個整數表示錯誤碼，這種方式很難維護錯誤碼，客戶端拿到錯誤碼還需要查表得知錯誤信息。更好的方式是用字符串表示錯誤代碼，不需要看文檔也能猜到錯誤原因。
可以在瀏覽器直接測試API，例如，輸入http://localhost:9000/api/users，就可以看到返回的JSON：
