web API 响应数据的设计

web API 响应数据的设计

《web API的设计与开发》第3章概览

• 数据格式
• 数据格式的指定方法
• jsonp
• 数据内部结构的思考方法
• 各个数据的格式
• 出错信息的表示

---

数据格式

• json,xml等

数据格式的指定方法

• 使用查询参数的方法
  https://api.example.com/v1/users?format=xml
• 使用扩展名的方法
  https://api.example.com/v1/users.json
• 使用在请求首部指定媒体类型的方法
  GET /v1/users
  Host: api.example.com
  Accept: application/json

jsonp

• 回避同源策略的一种手段
• 支持jsonp需要使用全局变量保存/回调函数
• 需要把错误信息放入消息体，正常返回200状态码

数据内部结构的思考方法

• 让用户来选择响应的内容
  http://api.example.com/v1/users/123?fields=name,age
• 封装，用统一的结构讲所有数据包装起来
  {
  “header”: {
  “status”: “success”,
  “errorCode”:0
  },
  “response”: {
  实际数据
  }
  }
• 尽可能数据扁平化，遇到层级结构有绝对优势也考虑用层级结构
  // 层级结构
  {
  “id”: 321423,
  “message”: “Hi!”,
  “sender”: {
  “id”: 345,
  “name”: “Taro”
  },
  “receiver”: {
  “id”: 12912,
  “name”: “Susan”
  }
  }
  // 扁平化方式
  {
  “id”: 321423,
  “message”: “Hi!”,
  “sender_id”: 345,
  “sender_name”: “Taro”
  “receiver_id”: 12912,
  “receiver_name”: “Susan”
  }
• 用对象进行封装数据(容易理解响应数据表示什么；结构统一；规避安全风险)
  //将序列原封不动地返回
  [
  {
  “id”: 12432,
  “name”: “Taro”
  },
  {
  “id”: 12433,
  “name”: “Kim”
  }
  ]
  //用对象进行封装后
  {
  “friends”: [
  {
  “id”: 12432,
  “name”: “Taro”
  },
  {
  “id”: 12433,
  “name”: “Kim”
  }
  ]
  }
• 分页操作: 返回序列个数，hasNext表示还有后续数据
  {
  “timelines”: […],
  “hasNext”: true
  }

各个数据的格式

• 使用多数API中使用的表示相同含义的单词
• 通过尽可能少的单词来表示
• 使用多个单词时，整个API连接单词的方法要统一(驼峰法，蛇形法，脊柱法)
• 尽可能不用奇怪的缩略语
• 注意单复数形式
• 描述性别 : 多使用gender male/female
• 日期格式 : 推荐 年/月/日(RFC 3339)顺序
• ID等巨大数值通常用字符串形式

出错信息的表示

• 通过状态码表示出错信息

• 向客户端返回详细的出错信息(填入响应消息首部/放入消息体)
  //填入响应消息头部
  X-MYNAME-ERROR-CODE: 2013
  X-MYNAME-ERROR-MESSAGE: Bad authentication token
  X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication

    //放入消息体
    {
         "error": {
              "code": 2013,
              "message": "Bad authentication token",
              "info": "http://docs.example.com/api/v1/authentication"
  
         }
    }
  

• 填写详细的出错信息，可以同时包含面向开发和非开发人员的信息
  {
  “error”: {
  “code”: 2013,
  “developerMessage”: “面向开发者的信息”,
  “userMessage”: “免息那个用户的信息”,
  “info”: “http://docs.example.com/api/v1/authentication”

         }
    }
  

• 发生错误时返回HTML
• 定期维护与状态码表
• 出于安全或其他原因考虑，需要返回模棱两可的信息