文档章节

REST接口设计规范总结

T
 Treize
发布于 01/26 22:07
字数 1740
阅读 183
收藏 0

URI格式规范
URI中尽量使用连字符”-“代替下划线”_”的使用
URI中统一使用小写字母
URI中不要包含文件(脚本)的扩展名

URI命名规范
文档(Document)类型的资源用名词(短语)单数命名
集合(Collection)类型的资源用名词(短语)复数命名
仓库(Store)类型的资源用名词(短语)复数命名
控制器(Controller)类型的资源用动词(短语)命名
URI中有些字段可以是变量,在实际使用中可以按需替换
CRUD的操作不要体现在URI中,HTTP协议中的操作符已经对CRUD做了映射。

HTTP请求方法的使用
GET方法用来获取资源
PUT方法可用来新增/更新Store类型的资源
PUT方法可用来更新一个资源的全部属性,使用时传递所有属性的值,即使有的值没有改变
PATCH方法更新资源的部分属性。因为 PATCH 比较新,而且规范比较复杂,所以真正实现的比较少,一般都是用 POST 替代
POST方法可用来创建一个资源
POST方法可用来触发执行一个Controller类型资源
DELETE方法用于删除资源

HTTP响应状态码的使用
200 (“OK”) 用于一般性的成功返回,不可用于请求错误返回
201 (“Created”) 资源被创建
202 (“Accepted”) 用于Controller控制类资源异步处理的返回,仅表示请求已经收到。对于耗时比较久的处理,一般用异步处理来完成。
204 (“No Content”) 此状态可能会出现在PUT、POST、DELETE的请求中,一般表示资源存在,但消息体中不会返回任何资源相关的状态或信息。
301 (“Moved Permanently”) 资源的URI被转移,需要使用新的URI访问
302 (“Found”) 不推荐使用,此代码在HTTP1.1协议中被303/307替代。我们目前对302的使用和最初HTTP1.0定义的语意是有出入的,应该只有在GET/HEAD方法下,客户端才能根据Location执行自动跳转,而我们目前的客户端基本上是不会判断原请求方法的,无条件的执行临时重定向
303 (“See Other”) 返回一个资源地址URI的引用,但不强制要求客户端获取该地址的状态(访问该地址)
304 (“Not Modified”) 有一些类似于204状态,服务器端的资源与客户端最近访问的资源版本一致,并无修改,不返回资源消息体。可以用来降低服务端的压力
307 (“Temporary Redirect”) 目前URI不能提供当前请求的服务,临时性重定向到另外一个URI。在HTTP1.1中307是用来替代早期HTTP1.0中使用不当的302
400 (“Bad Request”) 用于客户端一般性错误返回, 在其它4xx错误以外的错误,也可以使用400,具体错误信息可以放在body中
401 (“Unauthorized”) 在访问一个需要验证的资源时,验证错误
403 (“Forbidden”) 一般用于非验证性资源访问被禁止,例如对于某些客户端只开放部分API的访问权限,而另外一些API可能无法访问时,可以给予403状态
404 (“Not Found”) 找不到URI对应的资源
405 (“Method Not Allowed”) HTTP的方法不支持,例如某些只读资源,可能不支持POST/DELETE。但405的响应header中必须声明该URI所支持的方法
406 (“Not Acceptable”) 客户端所请求的资源数据格式类型不被支持,例如客户端请求数据格式为application/xml,但服务器端只支持application/json
409 (“Conflict”) 资源状态冲突,例如客户端尝试删除一个非空的Store资源
412 (“Precondition Failed”) 用于有条件的操作不被满足时
415 (“Unsupported Media Type”) 客户所支持的数据类型,服务端无法满足
429 (“Too Many Requests”) 客户端在规定的时间里发送了太多请求,在进行限流的时候会用到
500 (“Internal Server Error”) 服务器端的接口错误,此错误于客户端无关

HTTP Headers
Content-Type 标示body的数据格式
Content-Length body 数据体的大小,客户端可以根据此标示检验读取到的数据是否完整,也可以通过Header判断是否需要下载可能较大的数据体
Last-Modified 用于服务器端的响应,是一个资源最后被修改的时间戳,客户端(缓存)可以根据此信息判断是否需要重新获取该资源
ETag 服务器端资源版本的标示,客户端(缓存)可以根据此信息判断是否需要重新获取该资源,需要注意的是,ETag如果通过服务器随机生成,可能会存在多个主机对同一个资源产生不同ETag的问题
Store类型的资源要支持有条件的PUT请求
Location 在响应header中使用,一般为客户端感兴趣的资源URI,例如在成功创建一个资源后,我们可以把新的资源URI放在Location中,如果是一个异步创建资源的请求,接口在响应202 (“Accepted”)的同时可以给予客户端一个异步状态查询的地址
Cache-Control, Expires, Date 通过缓存机制提升接口响应性能,同时根据实际需要也可以禁止
客户端对接口请求做缓存。对于REST接口来说,如果某些接口实时性要求不高的情况下,我们可以使
用max-age来指定一个小的缓存时间,这样对客户端和服务器端双方都是有利的。一般来说只对GET
方法且返回200的情况下使用缓存,在某些情况下我们也可以对返回3xx或者4xx的情况下做缓存,可以防范错误访问带来的负载。
我们可以自定义一些头信息,作为客户端和服务器间的通信使用,但不能改变HTTP方法的性质。自
定义头尽量简单明了,不要用body中的信息对其作补充说明。

API 地址和版本
在 url 中指定 API 的版本是个很好地做法。如果 API 变化比较大,可以把 API 设计为子域名,比如 https://api.github.com/v3;也可以简单地把版本放在路径中,比如 https://example.com/api/v1。另一种做法是,将版本号放在HTTP头信息中。

© 著作权归作者所有

T
粉丝 0
博文 29
码字总数 23676
作品 0
海淀
技术主管
私信 提问
加载中

评论(0)

RESTful API 设计参考文献--restful-api-design-references

restful-api-design-references是RESTful API 设计参考文献列表,可帮助你更加彻底的了解REST风格的接口设计。 RESTful 介绍及设计思路 Principles of good RESTful API Design(译:好 REST...

匿名
2016/09/12
2.2K
2
SOA接口的两种常用实现比较:SOAP vs REST

SOA架构用于异构系统的协作,因此需要一种跨操作系统、跨语言的通用的消息交换格式。SOAP和REST都是基于文本的消息体,相比二进制消息而言具有跨平台的优势,因此被选作SOA接口的常用实现方法...

xinson
2015/05/25
190
0
转载:REST接口设计规范总结

简介 Representational State Transfer 简称 REST 描述了一个架构样式的网络系统。REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。 概念: 资源(...

messud4312
2018/05/30
32
0
高效 RESTful API 服务实现--rest-api-web

高效的 RESTful API 服务实现,基于 Jersey2 和嵌入式的轻量级的 servlet 容器 Jetty9, 这个是 war 包形式部署到 jetty 中运行,实现对用户的增、删、改、查操作,并且严格按照 RESTful 风格...

一刀
2017/06/25
2K
0
WEB开发中,使用JSON-RPC好,还是RESTful API好?

两者没有高下之分,无非是一种约定俗成的标准。习惯用RPC就用RPC,能理解REST就用REST。 JSON-RPC比较符合直观,格式也相对宽松; REST最近正流行,有自己的一套设计规范。 REST面对的疑问跟...

slagga
2018/03/01
122
0

没有更多内容

加载失败,请刷新页面

加载更多

PHP一致性hash代码

[TOC] PHP实现一致性hash bash命令 因为下面PHP代码的模拟用户用的是随机数,所以统计结果达不到绝对的均衡. php ./hash.php | sort | uniq -c | sort PHP代码 这是之前学的时候留下来的测试...

我爱吃炒鸡
今天
78
0
OSChina 周六乱弹 —— 现在看动弹的人都是什么状态

Osc乱弹歌单(2020)请戳(这里) 【今日歌曲】 @薛定谔的兄弟 :分享洛神有语创建的歌单「我喜欢的音乐」: 《夏日、教室与望着窗外的我》- Candy_Wind 手机党少年们想听歌,请使劲儿戳(这里...

小小编辑
今天
264
5
wamp环境安装redis扩展

1.查看phpinfo信息根据配置信息下载对应的扩展 关键信息:VC14,TS,x86 2.下载php_redis和php_igbinary扩展 php_redis扩展下载地址: https://windows.php.net/downloads/pecl/snaps/redis...

点滴课程
今天
36
0
开源商城开发笔记1-创建MyBatis示例

一、修改pom.xml,引入MyBatis,JUnit,Log4j <dependencies><dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.4</version>......

土龙
今天
56
0
The Best Way To Learn English in 2020 (In my humble opinion.)

✅Here is the plan: THINGS YOU WILL NEED: - 1 hour per day (30 minutes will work as well). - a notebook and a pen to write down new vocabulary each day. - an English song. - an ......

FalconChen
昨天
85
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部