WebAPI 的设计与开发
[TOC]

读书感悟

书写的很好,api 设计查漏补缺了,后面就是在实战中多。
日本人写书,有一个特点,就是啰啰嗦嗦,事无巨细。但是有的地方总给我一种,抓不住重点,无法把握全局和精髓的感觉。例如在 2.6 节讲 OAuth 的时候,用在线服务 A 和 B 举例,我的睁大眼睛,屏住呼吸才能理解作者想要表达的意思。同样的知识点,阮一峰就讲得很简洁明了 OAuth 2.0 的一个简单解释,我感觉日本人虽然严谨,但是有点严谨过头了。
聊到日本人,突然想起来王德峰老师评价日本文化。日本人缺乏幽默感,是因为其地理位置险恶,像一条虫蜷缩于太平洋地震带上,没办法退一步海阔天空,所以做事小心谨慎,没办法豁达。

第一章 什么是 web api

  • web api 与服务器返回的 html 的区别
    api 不是通过输入或点击链接来访问的,而是由程序进行调用的。HTML 是让人读的,api 是让机器读的。
  • Web API 是计算机领域的 UGC(User Generated Content)
  • 公开什么 api
    所有的在线服务,都可以公开 api,api 可以作为一个程序员的名片
  • 公开 api 是否有风险
    即使不公开 api,真想要获取数据的话,用爬虫爬取 html 也可以获取
  • api 设计的重要性
    • api 一经设计,就很少再更改,所以首次设计很重要
    • api 是程序员的名片
    • 设计良好的 api 可读性好,易于使用,易于传播
  • api 的一种分类
    • LSUD:Large Set of Unknown Developers 面向大量的开发者,例如 Twitter 的 api
    • SSKD:Small Set of Known Developers 面向少量已知开发者,例如公司内部的 api。设计 SSDK API 时,一个屏幕的内容使用一次 API 调用,一次保存使用一次 API 调用
  • api 的设计不必严格遵循 rest,尽信书不如无书

第二章 url 设计与请求的形式

  • 通过封装 sql 来设计 api 的思路是不可取的,这样不仅没法描述抽象的功能,还可能暴露服务端存储的数据结构
  • Good URI
    • 短小便于输入
    • 可读性好
    • 没有大小写混用
      HTTP 协议规定,模式和主机名必须小写,后面的地址是区分大小写的
    • 修改方便
      ✔️ http://api.example.com/v1/items/12345
      ✔️ http://api.example.com/v1/items/12346
    • 不会暴露服务端架构
    • 规则统一
      // 获取 id 为 100 的好友的信息
      http://api.example.com/friends/100
      // 给 100 的朋友发送消息
      http://api.example.com/friends/100/message
  • HTTP methods
    • GET
      get 方法有时候也会修改资源,例如在 get 数据的时候,将已读修改成未读,修改最后访问时间等信息
    • POST
      POST 用于新建资源
    • PUT
      PUT 通常只用于更新数据
    • DELETE
    • PATCH
    • HEAD
  • 将资源描述成 url,并用 HTTP 方法表示对其进行的操作,URL 中只包含名词,不包含动词和形容词!
  • 当需要使用多个单词描述一个资源的时候,使用连接符
    http://api.example.com/v1/users/12345/profile-image
  • 使用请求参数 ?还是路径
    看这个参数是否指代资源,例如下面的 access-token,并不指代资源,所以应该放在请求参数中
    ✔️ http://api.example.com/v1/users?access-token=xxx
    ❌ http://api.example.com/v1/users/access-token/xxx
  • 获取当前用户自身的数据
    http://api.example.com/v1/users/me
  • API 设计级别
    • REST LEVEL0 使用 HTTP
    • REST LEVEL1 引入资源的概念
    • REST LEVEL2 引入 HTTP 动词
    • REST LEVEL3 引入 HATEOAS 概念

第三章 响应数据的设计

  • 指定响应数据的格式
    • 使用请求参数指定
      http://api.example.com/v1/users?format=json
    • 使用 url 扩展名指定
      http://api.example.com/v1/users.json
    • 在请求的首部中指定
      GET /v1/users
      Host: api.example.com
      Accept: application/json
  • 响应数据的设计原则
    • 允许适当的冗余,进而减少 API 的请求次数
    • 响应数据的状态码语义,应该与响应数据契合
    • 响应数据应该尽可能的扁平化,不要封装太多的层次结构
  • 响应数据中的时间,通常用 unix 时间戳来表示,单位是秒
  • 出错信息的表示
    • 响应码要与出错信息契合!
    • 具体的出错信息,要在响应体中给出,包括更详细的错误码和错误描述

第四章 最大程度地利用 HTTP 协议规范

  • 5 开头的响应码表示服务端出错,4 开头的响应码表示客户端请求出错
  • 3 打头的响应码表示资源的地址变了,服务端返回一个新的地址
  • 重要的响应码
    • 401:Unauthorized 认证错误
    • 403:Forbidden 无权访问
    • 404:not found 资源未找到
    • 405:Method not Allowd 资源存在,但是请求的方法不对
    • 406:Not Acceptable 服务端不支持客户端请求的数据格式
    • 503:服务器在维护
  • HTTP 缓存
    为了降低访问服务端的次数,客户端将数据缓存起来,再次需要时,就从缓存中读取
    适合缓存的数据:生成后就不会变动的数据,例如历史的天气数据
    HTTP 缓存模型
    • 过期模型
      预先决定响应数据的保存期限,到达期限后就再次访问服务器
      在头信息中,加入
      // 3600 秒后过期
      Cache-Control: max-age=3600
      或者加入:
      Expire: Fri, 01 Jan 2015 00:00:00 GMT
      Cache-Control 的优先级更高
    • 验证模型
      采用询问服务器的方式,来判断缓存是否有效
    如果不想使用缓存,则配置如下:
    Cache-Control: no-cache
  • 指定媒体类型
    格式:顶层类型名称 / 子类型名称
    指定响应体的类型:
    Content-Type: application/json
    优先使用 application/xml,而不是 text/xml
    请求的类型:
    表示请求体的内容是 application/json,Accept 表示客户端能够接收的数据类型。
    Content-Type: application/json
    Accept: application/json
    Accept 可以枚举多种类型,还可以配置优先级:
    Accept: application/json, application/xml;q=0.9
  • 跨域访问相关
    客户端发起跨域请求时,会在头信息中携带一个 Origin
    当客户端通过跨域在头信息中加入 Cookie 或者 Authentication 认证信息时,服务器端认证通过后,需要在头信息中携带有:
    Access-Control-Allow-Credentials: true
    如果不携带的话,浏览器会直接拒绝来自服务器的响应请求。
常见的 MIME 媒体类型
媒体类型
数据格式
text/plain
纯文本
text/html
html 文件
application/xml
xml 文件
text/css
css 文件
application/javascript
javascript
application/json
json 文件
application/rss+xml
RSS 域
application/octet-stream
二进制数据
application/zip
zip 文件
image/jpeg
jpeg 图像
image/png
png 图像
image/svg+xml
svg 图像
multipart/form-data
多个数据组成的 web 表单数据
video/mp4
mp4 动画文件
application/vnd.ms-excel
excel 文件

第五章 开发方便更改设计的 web api

  • 在 url 中嵌入版本号
    http://api.example.com/v1/items/12345
  • 新的 api 发布后,旧的仍然使用

第六章 开发牢固的 web api

后面统一学习安全相关的知识。

web api 确认清单

  • URL 是否短小且容易输入
  • URL 是否能让人一眼看懂
  • URL 是否只有小写字母
  • URL 中是否只有名次,是否存在形容词和动词
  • URL 是否指代某资源
  • URL 是否容易修改
  • URL 是否会泄露服务端架构
  • URL 规则是否统一
  • 有没有使用合适的 HTTP 方法
  • URL 中的单词使用是否统一
  • URL 中不要加空格和需要编码的字符
  • URL 中多个单词之间要用 - 连接
  • 响应数据的格式是否指定
  • 响应数据是不是过度封装
  • 响应数据的结构有没有做到扁平化
  • 有没有返回合适的响应码
  • 出错时是否返回详细的错误信息
  • 服务器在维护时是否返回 503
  • 需不需要缓存
  • 需不需要进行版本控制
Last modified 6mo ago