说明:其实没有绝对的规范,达到90%即可。

理解RESTful架构:http://www.ruanyifeng.com/blog/2011/09/restful.html

RESTful API 设计指南:http://www.ruanyifeng.com/blog/2014/05/restful_api.html

GitHub标准RESTful API:https://api.github.com/

教程收集:

http://novoland.github.io/%E8%AE%BE%E8%AE%A1/2015/08/17/Restful%20API%20%E7%9A%84%E8%AE%BE%E8%AE%A1%E8%A7%84%E8%8C%83.html

http://imweb.io/topic/5707561f06f2400432c139a5(以下内容转自此篇文章)

http://www.coderli.com/translate-restful-standard-resolved/

http://blog.csdn.net/yue7603835/article/details/52536497

http://blog.csdn.net/u013731455/article/details/56278168

https://www.zhihu.com/question/28557115

URI

URI规范

  • 不要用大写
  • 单词间使用下划线'_'
  • 不使用动词,资源要使用名词复数形式,如:user、rooms、tickets
  • 层级 >= 三层,则使用'?'带参数

    users/1/address/2/citys (bad) /citys?users=1&address=2; (good)

Request

Method

  • GET:查询资源
  • POST:创建资源
  • PUT/PATCH

    • PUT:全量更新资源(提供改变后的完整资源)
    • PATCH:局部更新资源(仅提供改变的属性)
  • DELETE:删除资源

安全性与幂等性

  • 安全性:任意多次对同一资源操作,都不会导致资源的状态变化
  • 幂等性:任意次对同一资源操作,对资源的改变是一样的
  • Method 安全性 幂等性
    GET
    POST × ×
    PUT ×
    PATCH ×
    DELETE ×

兼容

很多客户只支持GET/POST请求,一般有两种方式模拟PUT等请求

  • 添加_method参数

    /users/1?_method=put&name=111
  • 添加X-HTTP-Method-Override请求头 (我们使用这种方式)
    X-HTTP-Method-Override: PUT

参数

Method

GET

  • 非id的参数使用'?'方式传输

    /users/1?state=closed
    POST、PATCH、PUT、DELETE
  • 非id的参数使用body传输,并且应该encode

过滤

?type=1&state=closed

排序

  • +升序,如?sort=+create_time,根据id升序
  • -降序,如?sort=-create_time,根据id降序

分页

?limit=10&offset=10
  • limit:返回记录数量
  • offset:返回记录的开始位置

单参数多字段

使用, 分隔,如

/users/1?fields=name,age,city

版本控制

三种方案:

  1. 在uri中加入版本: /v1/room/1
  2. Accept Header:Accept: v1
  3. 自定义 Header:X-Imweb-Media-Type: imweb.v1 (我们使用此方案)

自定义Media-Type参考资料github


状态码

成功

Code Method Describe
200 ALL 请求成功并返回实体资源
201 POST 创建资源成功

客户端错误

Code Method Describe
400 ALL 一般是参数错误
401 ALL 一般用户验证失败(用户名、密码错误等)
403 ALL 一般用户权限校验失败
404 ALL 资源不存在(github在权限校验失败的情况下也会返回404,为了防止一些私有接口泄露出去)
422 ALL 一般是必要字段缺失或参数格式化问题

服务器错误

CODE METHOD DESCRIBE
500 ALL 服务器未知错误

以上是常见的状态码,完整的状态码列表在这状态码

HATEOAS

在介绍HATEOAS之前,先介绍一下REST的成熟度模型

在介绍 HATEOAS 之前,先介绍一下 Richardson 提出的 REST 成熟度模型。该模型把 REST 服务按照成熟度划分成 4 个层次:

  • 第一个层次(Level 0)的 Web 服务只是使用 HTTP 作为传输方式,实际上只是远程方法调用(RPC)的一种具体形式。
  • 第二个层次(Level 1)的 Web 服务引入了资源的概念。每个资源有对应的标识符和表达。
  • 第三个层次(Level 2)的 Web 服务使用不同的 HTTP 方法来进行不同的操作,并且使用 HTTP 状态码来表示不同的结果。如 HTTP GET 方法来获取资源,HTTP DELETE 方法来删除资源。
  • 第四个层次(Level 3)的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。

简述

HATEOAS(Hypermedia as the engine of application state)是 REST 架构风格中最复杂的约束,也是构建成熟 REST 服务的核心。它的重要性在于客户端和服务器之间的解耦。

例子

分页

request请求,查询user,每页显示10条,从第10条开始显示(第二页)

/users?limit=10&offset=10

response

{
data: {
xxxx
},
meta: {
_link: [
{rel: 'self', href: 'xxx/users?limit=10&offset=10'},
{rel: 'first', href: 'xxx/users?limit=10&offset=0', title: 'first page'},
{rel: 'last', href: 'xxx/users?limit=10&offset=50', title: 'last page'},
{rel: 'prev', href: 'xxx/users?limit=10&offset=0', title: 'prev page'},
{rel: 'next', href: 'xxx/users?limit=10&offset=20', title: 'next page'}
]
}
}

_link返回了5个资源

  • rel: 'self',资源本身
  • rel: 'first',第一页资源
  • rel: 'last',最后一页资源
  • rel: 'prev',上一页资源
  • rel: 'next',下一页资源

权限相关

如用户查询一个订单

普通用户

request

/orders/1

response

{
data: {
xxx
},
meta: {
_link: [
{rel: 'self', href: 'xxx/orders/1'},
{rel: 'related', href: 'xxx/orders/1/payment', title: 'pay the order'}
]
}
}

_link返回两个资源

  • rel: 'self',资源本身
  • rel: 'related',与当前资源相关的资源,/order/1/payment用户可以使用此资源进行支付

权限用户

request

/orders/1

response

{
data: {
xxx
},
meta: {
_link: [
{rel: 'self', href: 'xxx/orders/1'},
{rel: 'edit', href: 'xxx/orders/1', title: 'edit the order'},
{rel: 'delete', href: 'xxx/orders/1', title: 'delete the order'}
]
}
}

此用户拥有修改与删除订单的权限,因此返回了3个资源

  • rel: 'self',资源本身
  • rel: 'edit',此用户可修改该资源
  • rel: 'delete',此用户可删除该资源

常用rel

rel describe
self 资源本身,每个资源表述都一个包含此关系
edit 指向一个可以编辑当前资源的链接
delete 指向一个可以删除当前资源的链接
item 如果当前资源表示的是一个集合,则用来指向该集合中的单个资源
collection 如果当前资源包含在某个集合中,则用来指向包含该资源的集合
related 指向一个与当前资源相关的资源
first、last、prev、next 分别用来指向第一个、最后一个、上一个和下一个资源

HATEOAS总结

由以上例子可以看出_link就是以Hyperlink表述资源与资源之间的关系,这种方式使客户端与服务端能很好的分离开来,只要接口的定义不变,客户端与服务端就可以独立的开发和演变。

RESTful API设计规范收集的更多相关文章

  1. rest-framework 序列化格式Restful API设计规范

    理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...

  2. Restful API设计规范及实战【说的比较清楚了】

    Restful API设计规范及实战   Restful API的概念在此就不费口舌了,博友们网上查哈定义文章很多,直入正题吧: 首先抛出一个问题:判断id为 用户下,名称为 使命召唤14(COD14 ...

  3. RESTful api 设计规范

    该仓库整理了目前比较流行的 RESTful api 设计规范,为了方便讨论规范带来的问题及争议,现把该文档托管于 Github,欢迎大家补充!! Table of Contents RESTful A ...

  4. 理解 RESTful API 设计规范

    RESTful是目前最流行的API设计规范,它是用于Web数据接口的设计.从字面可以看出,他是Rest式的接口,所以我们先了解下什么是Rest. REST与技术无关,它代表的是一种软件架构风格,RES ...

  5. Restful API设计规范及实战

    Restful API的概念在此就不费口舌了,博友们网上查哈定义文章很多,直入正题吧: 首先抛出一个问题:判断id为 用户下,名称为 使命召唤14(COD14) 的产品是否存在(话说我还是很喜欢玩类似 ...

  6. PHPer的项目RESTful API设计规范是怎样的?

    RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 什么是RESTful RESTful是一种软件设计风格, 主要用于客户端与服务端交互的软件. 一般来说RESTful ...

  7. RESTful API设计规范总结

    RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 它的大原则容易把握,但是细节不容易做对.本文总结 RESTful 的设计细节,介绍如何设计出易于理解和使用的 API. ...

  8. Restful API设计规范

    理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...

  9. Python 之 Restful API设计规范

    理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...

随机推荐

  1. 螺旋数字的python实现

    螺旋数字的算法简单实现. 示例 5 01 02 03 04 05 16 17 18 19 06 15 24 25 20 07 14 23 22 21 08 13 12 11 10 09 通过观察,外部 ...

  2. DBMS的工作模式

    数据库管理系统(DBMS)是指数据库系统中对数据进行管理的软件系统,它是数据库系统的核心组成部分,对数据库的一切操作(增删改查)都是通过DBMS进行的 DBMS的工作模式如下: 1>接受应用程序 ...

  3. billu_b0x靶场刷题

    https://www.vulnhub.com/ 里面有很多安全环境,只要下载相关镜像,在虚拟机上面搭建运行就可以练习对应靶场了. 第一步.信息收集 nmap扫描内网开放80端口的存活主机  nmap ...

  4. 在虚拟机linux环境下编译windows版adb fastboot

    原文出自:http://blog.chinaunix.net/uid-20546441-id-1746200.html 我根据虚拟机编译遇到的问题进行一些添加 [前提条件] Linux Android ...

  5. css--使用的四种方法

    前戏 之前学习了HTML相关的知识,也能简单的写一个hello world的页面.但是,只学HTML满足不了我们的需求,而HTML.CSS.JavaScript三者搭配使用才能更好的完成我们需要的效果 ...

  6. phpstorm使用Database关联数据库

    1.如图选择mysql 配置数据库连接及shh 点击Test Connection,如果成功,即可点击ok连接mysql数据库 2.如图选择所有的表 3.更新数据

  7. 一篇文章掌握nightwatch自动化测试

    nightwatch.js是一个web-ui自动化测试框架,被vue-cli深度整合进来.如果一个项目是基于vue-cli搭建的,基本可以做到开箱即用. 但是我们不可能一直都使用vue-cli.因为它 ...

  8. 使用window.open打开新窗口被浏览器拦截的解决方案

    问题描述: 代码中直接使用window.open('//www.baidu.com', '_blank');会被浏览器窗口拦截 原因浏览器为了维护用户安全和体验,在JS中直接使用window.open ...

  9. 我的java web之路(JSP基本语法)

    1.JSP注释 1.1输出注释 语法格式  <!--comment [<%= expression %>] --> <body> This is my JSP pa ...

  10. reversing.kr easykeygen 之wp

    补充: int(x,[base]): 就是将x(通常是一个字符串)按照base进制转换成整数. 比如: ’) ##转换成整数10 ) ##'按16进制转换,将得到整数16 ) ##得到255 int( ...