|
|
REST这个词是2000年Roy Fielding在他的博士论文中提出的，Fielding参与了http协议的设计，也是Apache web server项目的参与者。他的这篇博士论文可以说对互联网的软件设计产生了深远的影响。但是从字面上理解REST(Representational State Transfer, 表现层状态转移)是非常抽象的。因此，本篇文章试图将REST进行拆解，分别从以下几个部分来进行解读：
Resource 资源
REST忽略了主语，全称应该是 资源的表现层状态转移。所谓资源就是互联网上的各种资源，比如文本、图片、音频、视频等。在互联网上通过URI指定唯一的资源，所谓的’ 上网‘就是通过调用资源的URL来跟互联网上的一系列资源进行互动。
注：URI只代表资源的实体，严格地说，有些网址最后的 .html后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而URI应该只代表"资源"的位置。
Representational 表象
资源可以有各种具体的表现形式，比如文本可以有 xml格式， html格式， json格式，甚至是二进制格式，图片可以有 PNG格式， JPEG格式等。资源的一个具体表现形式，应该在HTTP请求的头信息中用 Accept和 Content-Type字段指定，这两个字段才是对"表现层"的描述。
State Transfer 状态转移
通过http动词来实现资源的状态转移，用 GET来请求资源，用 POST来新建资源，用 PUT来更新资源，用 DELETE来删除资源。
简明扼要的总结REST：
- 用URI来定位具体的资源
- 用HTTP请求的Content-Type字段来描述资源的表现形式
- 用HTTP动词来描述对资源的具体操作
RESTful API设计总结 随着近年来移动互联网的发展，各种客户端出不穷：Web，IOS，Android。因此需要一种机制使得各种客户端能够和服务端进行通讯，这就使得RESTful API的架构流行起来。RESTful是REST(表现层状态转化)的形容词形式，因此RESTful API就可以理解成“符合REST风格的API”。
格式规范 根据RFC3986定义，URL是大小写敏感的。所以为了避免歧义，尽量使用小写字母。
RESTful API 应具备良好的可读性，当url中某一个片段（segment）由多个单词组成时，建议使用 - 来隔断单词，而不是使用 _。这主要是因为，浏览器中超链接显示的默认效果是 文字并附带下划线，如果API以 _隔断单词，二者会重叠，影响可读性。
/api/featured-post/ # GOOD
/api/featured_post/ # WRONG |
协议 提供给用户的API，总是使用HTTPs协议。使用HTTPs协议还是HTTP协议本身和RESTful API并无关系，但是这对于提高网站的安全性很重要。
域名 API应该放在专有域名下，比如 https://api.example.com/v1。也可以简单地把版本放在URL中，比如 https://www.example.com/api/v1
版本 API的版本号应该放在URL中：
名词应该使用复数 所用的名词往往和数据库的表名对应，而数据库的表是一组记录的集合，因此URL中的名词即表示一组资源的集合，故URI中的名词要使用复数
URL中不能使用动词 URI代表着一个资源，是一个实体，应该是名词，而不要把具体的动作放在URL中，对资源的操作应该通过HTTP的动词来实现。
不符合CRUD的情况 如果实在无法表示，也可使用动词，例如search没有对应的HTTP方法，可以在路径中使用search，更加直观 http://api.xxx.com/apiv3/search?timestamp=123213218&user_id=4192121&keyword=2134789。再例如创建了博客网站，如果想要发布一个博客，可以使用 POST /articles/{:id}/publish
用HTTP动词表示对资源的操作 使用HTTP协议里的动词来实现资源的获取、删除、添加等操作
- GET：从服务器获取资源
- POST：在服务器新建一个资源
- PUT：在服务器更新资源（客户端提供改变后的完整资源）
- PATCH：在服务器更新资源（客户端提供改变的属性）
- DELETE：从服务器中删除资源
HTTP状态码- 200 OK - [GET]：服务器成功返回用户请求的数据
- 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
- 204 NO CONTENT - [DELETE]：用户删除数据成功
- 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
- 401 UNAUTHORIZED：表示用户没有权限（令牌、用户名、密码错误）
- 404 NOT FOUND：用户发出的请求针对的是不存在的记录，服务器没有进行操作
- 500 INTERNAL SERVER ERROR：服务器发生错误，用户将无法判断发出的请求是否成功
其它 API的身份认证应该使用OAuth 2.0框架
服务器返回的数据格式，应该尽量使用JSON，避免使用XML。JSON有可读性强，结构紧凑，支持的语言种类多的特点，因此JSON是RESTful API最常用的返回格式。
----------------------------
原文链接:https://www.jianshu.com/p/955eb2faa354
程序猿的技术大观园：www.javathinker.net
[这个贴子最后由 flybird 在 2020-06-15 09:36:40 重新编辑]
|
|
Java技术网站 → 『 Java开发技术 』 → 『 Spring框架和各种开源软件技术专题 』 → RESTful架构和RESTful API设计总结
消息
查看
搜索
好友
邮件
复制
引用
IP: 已设置保密
