转载:阮一峰 Rest API设计原则

 网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......)。

  因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致 API 构架的流行,甚至出现"API First"的设计思想。RESTful API 是目前比较成熟的一套互联网应用程序的 API 设计理论。我以前写过一篇《理解 RESTful 架构》,探讨如何理解这个概念。

  今天,我将介绍 RESTful API 的设计细节,探讨如何设计一套合理、好用的 API。我的主要参考资料是这篇《Principles of good RESTful API Design》

  一、协议

  API 与用户的通信协议,总是使用 HTTPs 协议

  二、域名

  应该尽量将 API 部署在专用域名之下。

https://api.example.com

  如果确定 API 很简单,不会有进一步扩展,可以考虑放在主域名下。

https://example.org/api/

  三、版本(Versioning)

  应该将 API 的版本号放入 URL。

https://api.example.com/v1/

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

  四、路径(Endpoint)

  路径又称"终点"(endpoint),表示 API 的具体网址。

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

  举例来说,有一个 API 提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

  五、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:指定返回记录的开始位置。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animaltypeid=1:指定筛选条件

  参数的设计允许存在冗余,即允许 API 路径和 URL 参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET
/animals?zoo_id=ID 的含义是相同的。

  七、状态码(Status Codes)

  服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的 HTTP 动词)。

200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED
- [POST/PUT/PATCH]:用户新建或修改数据成功。
204 NO CONTENT - [DELETE]:用户删除数据成功。
400
INVALID REQUEST -
[POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。。
404 NOT FOUND -
[*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
500 INTERNAL SERVER ERROR -
[*]:服务器发生错误,用户将无法判断发出的请求是否成功。

  状态码的完全列表参见这里

  八、返回结果

  针对不同操作,服务器向用户返回的结果应该符合以下规范。

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。

  (完)

时间: 2024-10-30 01:31:34

转载:阮一峰 Rest API设计原则的相关文章

Stack的三种含义(转载--阮一峰)

作者: 阮一峰 学习编程的时候,经常会看到stack这个词,它的中文名字叫做"栈". 理解这个概念,对于理解程序的运行至关重要.容易混淆的是,这个词其实有三种含义,适用于不同的场合,必须加以区分. 含义一:数据结构 stack的第一种含义是一组数据的存放方式,特点为LIFO,即后进先出(Last in, first out). 在这种数据结构中,数据像积木那样一层层堆起来,后面加入的数据就放在最上层.使用的时候,最上层的数据第一个被用掉,这就叫做"后进先出". 与这

JavaScript API 设计原则

网+线下沙龙 | 移动APP模式创新:给你一个做APP的理由>> 好的 API 设计:在自描述的同时,达到抽象的目标. 设计良好的 API ,开发者可以快速上手,没必要经常抱着手册和文档,也没必要频繁光顾技术支持社区. 流畅的接口 方法链:流畅易读,更易理解 //常见的 API 调用方式:改变一些颜色,添加事件监听 var elem = document.getElementById("foobar"); elem.style.background = "red&

深入浅析JavaScript的API设计原则(转载)

一.接口的流畅性 好的接口是流畅易懂的,他主要体现如下几个方面: 1.简单 操作某个元素的css属性,下面是原生的方法: ? 1 document.querySelectorAll('#id').style.color = 'red'; 封装之后 ? 1 2 3 4 function a(selector, color) { document.querySelectorAll(selector)[].style.color = color } a('#a', 'red'); 从几十个字母长长的一

JavaScript 的 API 设计原则

前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时的原则,总共包含了七个大块.系卤煮自己总结的一些经验教训.同时也参考了一些文章,地址会在后面贴出来.很难做到详尽充实,如果有好的建议或者不对的地方,还望不吝赐教斧正. 一.接口的流畅性 好的接口是流畅易懂的,他主要体现如下几个方面: 1.简单 操作某个元素的css属性,下面是原生的方法: document.querySelectorAll('#id').style.color = 'red'; 封装之后 function a(

JavaScript的api设计原则

一.接口的流畅性 好的接口是流畅易懂的,他主要体现如下几个方面: 1.简单 操作某个元素的css属性,下面是原生的方法: document.querySelector('#id').style.color = 'red'; 封装之后 function a(selector, color) {  document.querySelector(selector).style.color = color } a('#a', 'red'); 从几十个字母长长的一行到简简单单的一个函数调用,体现了api简

RESTful API设计原则与规范

一.背景与基础概念 2 二.RESTful API应遵循的原则 3 1.协议(Protocol) 3 2.域名(ROOT URL) 3 3.版本(Versioning) 3 4.路径(Endpoints) 3 5.HTTP动词(HTTP Verbs) 4 6.过滤信息(Filtering) 5 7.状态码(Status Codes) 5 8.错误处理(Error handling) 6 9.返回结果(Response) 6 10.使用HATEOAS的Hypermedia API 6 11.认证(

Atitit. Api 设计 原则 ---归一化

1.1. 叫做归一化1 1.2. 归一化的实例:一切对象都可以序列化/toString  通过接口实现1 1.3. 泛文件概念.2 1.4. 游戏行业的一切皆精灵2 1.1. 叫做归一化 接口继承实质上是要求"做出一个良好的抽象,这个抽象规定了一个兼容接口,使得外部调用者无需关心具体细节,可一视同仁的处理实现了特定接口的所有对象"--这在程序设计上,叫做归一化. 归一化使得外部使用者可以不加区分的处理所有接口兼容的对象集合--就好象linux的泛文件概念一样,所有东西都可以当文件处理,

atitit.api设计 方法 指南 手册 v2 q929.docx

atitit.api设计 方法 指南 手册 v2 q929.docx atitit.api设计原则与方法 1. 归一化(锤子钉子理论)1 1.1. 链式方法2 1.2. 规则5:建立返回值类型2 1.3. 参数接收 JSON 对象2 1.4. 参数默认值2 1.5. 命名参数 support by map2 1.6.  处理类型 类型自动转换4 1.7.  处理 undefined null  empty5 1.8. .使用结构化语法5 1.9. 设置和获取操作,可以合二为一:方法越多,文档可能

面向对象的设计原则

面向对象设计原则是学习设计模式的基础,每一种设计模式都符合某一种或者多种面向对象设计原则.通过在软件开发中使用这些原则可以提高软件的可维护行和可用性,让我们可以设计出更加灵活也更加容易扩展的软件系统,实现可维护可复用的目标.在使用面向对象的思想进行系统设计时,前人共总结出了7条原则,它们分别是:单一职责原则.开闭原则.里氏替换原则.依赖注入原则.接口分离原则.迪米特原则和合成复用原则. 1.单一职责原则(SRP) 单一职责原则的核心思想就是:系统中的每一个对象都应该只有一个单独的职责,而所有对象