WEB开辟面面谈之（4）——RESTful API 设想指南

2023年8月5日 248次阅读 来源: 张炳

>>>点击猎取更多文章<<<

收集应用程序，分为前端和后端两个部份。当前的发展趋势，就是前端装备屡见不鲜（手机、平板、桌面电脑、其他专用装备……）。

因而，必须有一种一致的机制，轻易差别的前端装备与后端举行通讯。这致使API构架的盛行，以至涌现”API First”的设想头脑。RESTful API是现在比较成熟的一套互联网应用程序的API设想理论。

协定

API与用户的通讯协定，老是运用HTTPs协定。

域名

应当只管将API布置在专用域名之下: https://api.example.com 。假如肯定API很简单，不会有进一步扩大，能够斟酌放在主域名下：https://example.org/api/。

版本（Versioning）

应当将API的版本号放入URL:https://api.example.com/v1/ 。 另一种做法是，将版本号放在HTTP头信息中，但不如放入URL轻易和直观。Github采纳这类做法。

途径（Endpoint）

途径又称”尽头”（endpoint），示意API的详细网址。

在RESTful架构中，每一个网址代表一种资本（resource），所以网址中不能有动词，只能有名词，而且所用的名词每每与数据库的表格名对应。一般来说，数据库中的表都是同种纪录的”鸠合”（collection），所以API中的名词也应当运用复数。

举例来说，有一个API供应动物园（zoo）的信息，还包含种种动物和雇员的信息，则它的途径应当设想成下面如许。

HTTP动词

关于资本的详细操纵范例，由HTTP动词示意。 经常使用的HTTP动词有下面五个（括号里是对应的SQL敕令）。

  • GET（SELECT）：从服务器掏出资本（一项或多项）。
  • POST（CREATE）：在服务器新建一个资本。
  • PUT（UPDATE）：在服务器更新资本（客户端供应转变后的完全资本）。
  • PATCH（UPDATE）：在服务器更新资本（客户端供应转变的属性）。
  • DELETE（DELETE）：从服务器删除资本。

另有两个不经常使用的HTTP动词。

  • HEAD：猎取资本的元数据。
  • OPTIONS：猎取信息，关于资本的哪些属性是客户端能够转变的。

下面是一些例子。

  • GET /zoos：列出一切动物园
  • POST /zoos：新建一个动物园
  • GET /zoos/ID：猎取某个指定动物园的信息
  • PUT /zoos/ID：更新某个指定动物园的信息（供应该动物园的悉数信息）
  • PATCH /zoos/ID：更新某个指定动物园的信息（供应该动物园的部份信息）
  • DELETE /zoos/ID：删除某个动物园
  • GET /zoos/ID/animals：列出某个指定动物园的一切动物
  • DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

过滤信息（Filtering）

假如纪录数目许多，服务器不可能都将它们返回给用户。API应当供应参数，过滤返回效果。下面是一些罕见的参数。

  • ?limit=10：指定返回纪录的数目。
  • ?offset=10：指定返回纪录的最先位置。
  • ?page=2&per_page=100：指定第几页，以及每页的纪录数。
  • ?sortby=name&order=asc：指定返回效果根据哪一个属性排序，以及排序递次。
  • ?animal_type_id=1：指定挑选前提。

参数的设想许可存在冗余，即许可API途径和URL参数偶然有反复。比方，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的寄义是雷同的。

状况码（Status Codes）

服务器向用户返回的状况码和提醒信息，罕见的有以下一些（方括号中是该状况码对应的HTTP动词）。

  • 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 – [*]：服务器发作毛病，用户将没法推断发出的要求是不是胜利。

毛病处理（Error handling）

假如状况码是4xx，就应当向用户返回失足信息。一般来说，返回的信息中将error作为键名，失足信息作为键值即可。

{
    error: "Invalid API key"
}

返回效果

针对差别操纵，服务器向用户返回的效果应当相符以下范例。

  • GET /collection：返回资本对象的列表（数组）
  • GET /collection/resource：返回单个资本对象
  • POST /collection：返回新天生的资本对象
  • PUT /collection/resource：返回完全的资本对象
  • PATCH /collection/resource：返回完全的资本对象
  • DELETE /collection/resource：返回一个空文档

Hypermedia API

RESTful API最好做到Hypermedia，即返回效果中供应链接，连向其他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示意返回范例。

Hypermedia API的设想被称为HATEOAS。Github的API就是这类设想，接见api.github.com会获得一个一切可用API的网址列表。

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}

从上面能够看到，假如想猎取当前用户的信息，应当去接见api.github.com/user，然后就获得了下面效果。


{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

上面代码示意，服务器给出了提醒信息，以及文档的网址。

其他

(1)API的身份认证应当运用OAuth 2.0框架。

(2)服务器返回的数据花样，应当只管运用JSON，防止运用XML。

文章转自阮一峰的 RESTful API 设想指南,恰当精简少部份语句

    原文作者：张炳
    原文地址: https://segmentfault.com/a/1190000015572852
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞