自從Roy Fielding博士在2000年他的博士論文中提出REST（Representational State Transfer）風(fēng)格的軟件架構(gòu)模式后，REST就基本上迅速取代了復(fù)雜而笨重的SOAP，成為Web API的標(biāo)準(zhǔn)了。

什么是Web API呢？

如果我們想要獲取一篇Blog，輸入http://localhost:9000/blog/123，就可以看到id為123的Blog頁面，但這個(gè)結(jié)果是HTML頁面，它同時(shí)混合包含了Blog的數(shù)據(jù)和Blog的展示兩個(gè)部分。對于用戶來說，閱讀起來沒有問題，但是，如果機(jī)器讀取，就很難從HTML中解析出Blog的數(shù)據(jù)。

如果一個(gè)URL返回的不是HTML，而是機(jī)器能直接解析的數(shù)據(jù)，這個(gè)URL就可以看成是一個(gè)Web API。比如，讀取http://localhost:9000/api/blogs/123，如果能直接返回Blog的數(shù)據(jù)，那么機(jī)器就可以直接讀取。

REST就是一種設(shè)計(jì)API的模式。最常用的數(shù)據(jù)格式是JSON。由于JSON能直接被JavaScript讀取，所以，以JSON格式編寫的REST風(fēng)格的API具有簡單、易讀、易用的特點(diǎn)。

編寫API有什么好處呢？由于API就是把Web App的功能全部封裝了，所以，通過API操作數(shù)據(jù)，可以極大地把前端和后端的代碼隔離，使得后端代碼易于測試，前端代碼編寫更簡單。

一個(gè)API也是一個(gè)URL的處理函數(shù)，我們希望能直接通過一個(gè)@api來把函數(shù)變成JSON格式的REST API，這樣，獲取注冊用戶可以用一個(gè)API實(shí)現(xiàn)如下：

@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這個(gè)decorator只要編寫好了，就可以把任意的URL處理函數(shù)變成API調(diào)用。

新建一個(gè)apis.py，編寫@api負(fù)責(zé)把函數(shù)的返回結(jié)果序列化為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進(jìn)行處理。我們定義一個(gè)APIError，這種Error是指API調(diào)用時(shí)發(fā)生了邏輯錯(cuò)誤（比如用戶不存在），其他的Error視為Bug，返回的錯(cuò)誤代碼為internalerror。

客戶端調(diào)用API時(shí)，必須通過錯(cuò)誤代碼來區(qū)分API調(diào)用是否成功。錯(cuò)誤代碼是用來告訴調(diào)用者出錯(cuò)的原因。很多API用一個(gè)整數(shù)表示錯(cuò)誤碼，這種方式很難維護(hù)錯(cuò)誤碼，客戶端拿到錯(cuò)誤碼還需要查表得知錯(cuò)誤信息。更好的方式是用字符串表示錯(cuò)誤代碼，不需要看文檔也能猜到錯(cuò)誤原因。

可以在瀏覽器直接測試API，例如，輸入http://localhost:9000/api/users，就可以看到返回的JSON：

最新評(píng)論