网站建设万户,网站策划与建设阶段的推广,淄博网站制作高端形象,网站建设使页面内容居中文章目录 1. 特征2. 优点3. 动作1. GET 获取资源2. POST 创建资源3. PUT 整体替换4. PATCH 部分替换5. DELETE 删除资源 4. 示例 RESTful是一种API的设计风格#xff0c;他和GraphQL #xff0c;JSON-RPC#xff0c;WebService类似#xff0c;用于定义在CS、BS架构下暴露服… 文章目录 1. 特征2. 优点3. 动作1. GET 获取资源2. POST 创建资源3. PUT 整体替换4. PATCH 部分替换5. DELETE 删除资源 4. 示例 RESTful是一种API的设计风格他和GraphQL JSON-RPCWebService类似用于定义在CS、BS架构下暴露服务端接口。此次设计对接规范将使用RESTful作为标准。
1. 特征
RESTful风格的特点是
① URI资源化
即URI代表的是资源而不包含动作。比如一个班级有很多学生我们可以这样表示/class/students
② 动作由HTTP头里的方法决定
比如我们想新增一个学生我们可以用POST方法
POST /class/students
{name: Jake,age : 18
}我们想查看当前有哪些学生可以用GET方法
GET /class/students我们想查看某学生的具体信息可以用路径指定到某一个ID
GET /class/students/1我们想要开除id为1的学生可以用DELETE方法
DELETE /class/students/1HTTP头里面的方法决定了动作后后端实现也应该严格根据动作来比如GET请求不应该对数据造成任何更改如此我们对权限控制便非常方便例如如果是访客我们可以只开放GET方法而对于ADMIN我们可以开放GET,POST,DELETE等方法。
大多数就是做CRUD用HTTP头部动作可以很好满足。
③ 资源的表现由Content-Type决定
HTTP请求的头信息中Accept和Content-Type字段是对资源的表现描述。例如指定是JSON格式还是HTML格式。
④ 无状态
无状态是指客户端无状态例如你不应该在客户端使用类似的逻辑
if (hasStudent(Jake)) {getStudentInfo(Jake);
}因为hasStudent和getStudentInfo调用之间可能别人已经将Jake删除了你的状态维护不一定准确。 你可以直接getStudentInfo(“Jake”)没有则返回失败即可。 服务端可以维护一些状态但最好不要维护太多例如HTTP登录状态是应该维护的但是记录并强制要求用户A是否请求过某个URL再请求另一个URL这种设计就不应该了。
⑤ 数据安全
使用HTTPS协议加密数据。
我们对接统一采用RESTful方式的HTTPS为了加密请求内容为JSON格式其中安全、幂等性、无状态之类的约束请产品线严格按照Restful规定设计。
2. 优点
① 减少沟通成本
API是开放给别人使用的由于有既有的约定会让沟通成本大大减少这是API提供者最应该考虑的。
② 能够接纳多种客户端(适用于大多数CS BS架构程序)
不止是web程序基本上的CS架构程序都可以使用RESTful提供API这样不论是WEB Client还是Windows APP还是Mobile APP都可以轻松使用服务端的API。
③ 思维方式转换为以资源为中心
传统的方式是以操作为中心例如create_user, query_students。
类似于面向对象以对象为中心RESTful推崇以资源为中心说不上绝对好但的确会引导大家考虑资源本身关注内聚性关注权限关注资源间关联。
④ 扩展方便
无状态设计对横向扩展非常方便因为API之间解耦比较好资源解耦也比较好。 还有一个叫 hypertext-driven 的东西类似于自描述但是用起来也不方便在CodeReview工具提供的API便是这种方式优点是服务端可以随意更换URL缺点是请求前要去查询一下该请求什么路径。例如github的参考https://api.github.com/
⑤ 建立在HTTP协议基础之上
HTTP协议里面规定的东西很多例如缓存压缩代理加密穿透等等都已经让HTTP帮忙完成了给很多实现减负。
3. 动作
1. GET 获取资源
举例获取学生Jake的信息。
GET /class/students?nameJake2. POST 创建资源
创建资源不会指定资源ID但创建完成后通常会返回资源的ID这样后续可以通过资源ID操作此资源。
举例创建学生。
POST /class/students
{name: Jake, age : 18, score: 0}3. PUT 整体替换
为了定位资源要求路径上有资源的唯一ID。
举例替换ID为2的学生的信息为如下新信息。
PUT /class/students/2
{name: Jim,age: 19}# 此操作将原本ID为2的学生的所有属性冲掉了替换后ID为2的学生整体内部数据结构变为
{id: 2, name: Jim,age: 19}异常
① 如果Playload为空返回失败。
② 如果Playload为{}是正确的表示清空重置例如上述示例内部数据结构将变为{“id”: 2}
4. PATCH 部分替换
为了定位资源要求路径上有资源的唯一ID。
举例更新ID为2的学生的年龄从之前的18岁更新为20岁。
PATCH /class/students/2
{age: 20}# 这里ID为2的学生的其他属性保留整体内部数据结构变成
{id: 2, name: Jake, age : 20, score: 0}异常
① 如果Playload为空或{}返回失败。
② 对于嵌套的结构如果是正常书写表示整体替换如果是点分结构表示部分更新。
比如
{id: 2, name: Jake, age : 20, score: {English: 86, Chinese:88, math:99}}子结构更新
PATCH /class/students/2
{score: {math:100}}# 替换后为
{id: 2, name: Jake, age : 20, score: {math:100}}子结构更新
PATCH /class/students/2
{score.math: 100}# 替换后为
{id: 2, name: Jake, age : 20, score: {English: 86, Chinese:88, math:100}}③ 对于数组标准用法是表示整体替换而不能增删。
比如
{id: 2, name:Jake, friends: [Jim, Marry, Jake]}执行整体替换
PATCH /class/students/2
{friends: [Bob]}# 替换后为
{id: 2, name:Jake, friends: [Bob]}为了支持增加和删除功能我们在URL参数上附带_arrayop[add,remove]用于表示增删数组。
例如
{id: 2, name:Jake, friends: [Jim, Marry, Jake]}PATCH /class/students/2?_arrayopadd
{friends: [Bob]}# 增加后为
{id: 2, name:Jake, friends: [Jim, Marry, Jake, Bob]}PATCH /class/students/2?_arrayopremove
{friends: [Jim]}# 删除后为
{id: 2, name:Jake, friends: [Marry, Jake]}这种做法的缺陷是一个_arrayop控制了整个Playload的array动作所以同一Playload如果需要多种动作的情况请拆分为多次请求。
5. DELETE 删除资源
DELETE里面能不能带payload这个RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content是这么规定的A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.
所以并没有禁止是否支持依赖于服务端实现比如某些版本的Tomcat或 Jetty就会忽略payload。
而OpenAPI3.0定义里面描述为
The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
说明对OpenAPI规范而言这种模棱两可的描述是明确要ignored的。
经过我们的实践发现DELETE带payload需求很多所以我们明确一下支持DELETE带payload的行为假如遇到实现不支持时请使用DELETE Over POST实现。
举例
删除ID为2的学生。
DELETE /class/students/2删除有Jim这个朋友的所有学生。
DELETE /class/students
{friends: [Jim]}或表达为DELETE Over POST
POST /class/students?_methodDELETE
{friends: [Jim]}4. 示例
AllArgsConstructor
Data
public class Person {private String id;private String name;private int age;
}RequestMapping(/api/v1/user)
RestController
public class UserController {PostMappingpublic String insertUser( Validated RequestBody Person person){System.out.println(person);return person;}DeleteMappingpublic String deleteUser(Validated RequestBody Person person){System.out.println(person);return person;}
}RequestMapping(/api/v1/user)
RestController
public class UserController {PatchMappingpublic String updateUser(Validated RequestBody ListString ids){System.out.println(ids);return person;}DeleteMappingpublic String deleteUser(Validated RequestBody ListString ids){System.out.println(ids);return person;}
}
