api的设计与开发,读书总结

July 10, 2020
api restful

引言

这是观看书籍这本书时,作的笔记

1 url命名的问题

http://api.example.com/friends?id=100 获取好友信息
http://api.example.com/friend/100/message 给好友发送消息

提倡:

http://api.example.com/friends/100
http://api.example.com/friends/100/message

2 使用什么PATH参数

比如DELETE http://api.example.com/v1/users/:id/friends/:id 删除好友,这里用的是好友ID,而不是好友关系记录的ID, 有两个原因:

3 神奇的定语

restful接口提倡用名词来表示资源,那获取好友(可能有几个)的动态列表,如何设定URL?

GET http://api.example.com/v1/users/:id/friends/updates,就是这个updates表示所有好友的更新

4 尽量减少api数量

为了完成一项任务,需要多次访问api,这样的api设计叫作Chatty API,会加大网络流量的消耗,增加客户端的处理工序,给用户留下难用的印象。因此尽可能多地返回信息, 但是如果返回了大量的客户端用不上的信息,却触犯另一个原则,尽可能发送较少数据量。用例复杂多样的话,确定返回合适的结果也是非常困难的,服务范围较大的API, 常用的应对办法就是使用户能够选择要获取的项目,比如在API调用时通过查询参数来指定,比如:/v1/users/123456?fields=name,age,也可以用设定响应群组,每一个组对应一些 返回数据项。

5 是否要封装

比如按照header/response来封装返回的数据,这里header放一些http状态字,就没有充分利用HTTP协议的机制,但是JSONP的时候,使用封装机制会更加便利,因为JSONP的情况下, 浏览器在读取数据时无法访问状态码及响应消息体。另外,返回的数据尽量扁平化。

6 日期的格式

通常有RFC 822/RFC 850/ANSIC的asctime()格式/RFC 3339/UNIX时间戳(epoch秒),提供使用RFC3339标准格式,比如:2015-10-12T11:30:22+09:00, 但是HTTP header中的时间仅支持前面三种格式,而且如果一开始就可以预测用户的状态,比如调用API的客户端仅仅是公司内部的智能手机应用,可以用简洁的unix时间戳也可以。

RFC3339有几个特点:

7 错误信息的返回

twitter的做法是将错误以序列的形式返回,非常适合多个错误同时发生时的描述:

{
  "error":[ 
    {
      "message": "Bad Authentication data",
      "code": 215
    }
  ]
  • code最好是分组,比如1字开头的表示哪一类,2字开头表示用户信息错误等
  • 还可以考虑将信息区分为面向用户的,和面向开发者的:developerMessage/userMessage
  • 可以考虑接口文档提示出来:"info" : "https://docs.xx/api/v1/authentication"

loading