# Day 9 - 編寫API 自從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實現如下： ``` @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： ``` 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：