如何设计一个 RestfulApi

[george-es]

在开发 BFF 层时候，会涉及到很多 api 设计，无论是命名还是请求方法，没有一定的套路，会很慕凌两可，没有任何头绪。

基于这些痛点，从 8 个维度对 API 进行探讨

• 协议

  基本上都是 http 或 https 协议

• 域名

  如果是大型服务，一般会为 api 开专属域名

   https://api.xxx.com
  

  不过，一般来说，对于简单的 api 都是加在主域名下面

   https://xxx.com/api/
  

• 版本

  随着迭代的进行，api 可能有 v1，v2，v3 等，这样的设计的好处是，不同版本下接口含义相同无所谓，譬如说，同样是部署功能，v1 版可能是 a 逻辑，v2 版可能是 b 逻辑，这样可以兼容旧版本

   https://xxx.com/api/v1/
   https://xxx.com/api/v2/
  

  另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。

• 路径

  路径又称"终点"（endpoint），表示 API 的具体网址。

  在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以 API 中的名词也应该使用复数。

   https://xxx.com/api/v1/zoos
  

• 方法

  • GET：从服务器取出资源
  • POST：在服务器新建一个资源
  • PUT：在服务器更新资源
  • DELETE：从服务器删除资源

• 过滤信息（Query）

  综合来说，对于 GET 请求，用到 query 时要想着过滤两个字

   ?limit=10：指定返回记录的数量
   ?offset=10：指定返回记录的开始位置
   ?page=2&per_page=100：指定第几页，以及每页的记录数。
   ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
   ?animal_type_id=1：指定筛选条件
  

• 状态码

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
  • 204 NO CONTENT - [DELETE]：用户删除数据成功。
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
  • 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

• Hypermedia API

  这是一个新的思路，Hypermedia API 是指返回结果中提供链接，连向其他 API 方法，使得用户不查文档，也知道下一步应该做什么。

  譬如当用户向 api.example.com 的根目录发出请求，会得到这样一个文档。

   {"link": {
     "rel":   "collection https://www.example.com/zoos",
     "href":  "https://api.example.com/zoos",
     "title": "List of zoos",
     "type":  "application/vnd.yourformat+json"
   }}
  

  文档中有一个 link 属性，用户读取这个属性就知道下一步该调用什么 API 了。rel 表示这个 API 与当前网址的关系（collection关系，并给出该collection的网址），href 表示 API 的路径，title 表示 API 的标题，type 表示返回类型。