简介

REST(Representational State Transfer):表象层状态转变
 
RESTful对api进行规范和约束,使得api统一规范,增强api的可读性,便于开发。
 

设计原则

1、每一个URI代表一种资源
 
2、客户端通过四个HTTP动词(get、post、put、delete),对服务器端资源进行操作
 
因此,这种风格的接口url中没有动词,而是通过四个HTTP动词(get、post、put、delete)来代表动作。

Http动词

分别对应四种基本操作:

  • GET用来获取资源
  • POST用来新建资源(也可以用于更新资源)
  • PUT用来更新资源
  • DELETE用来删除资源

具体实施

版本控制

如github开放平台的API:http://developer.github.com/v3/ 可以发现,一般的项目加版本v1,v2,v3版本号,为的是兼容一些老版本的接口,这个加版本估计只有大公司大项目才会去使用。

参数命名规范

query parameter可以采用驼峰命名法,也可以采用下划线命名的方式,推荐采用下划线命名的方式,据说后者比前者的识别度要高,其中,做前端开发基本都后后者,而做服务器接口开发基本用前者。
http://example.com/api/users/today_login 获取今天登陆的用户
http://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列

url命名规范

API 命名应该采用约定俗成的方式,保持简洁明了。在RESTful架构中,每个url代表一种资源,所以url中不能有动词,只能有名词,并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可
不规范的的url,冗余没有意义,形式不固定,不同的开发者还需要了解文档才能调用。
http://example.com/api/getallUsers //GET 获取所有用户
http://example.com/api/getuser/1 //GET 获取标识为1用户信息
http://example.com/api/user/delete/1 //GET/POST 删除标识为1用户信息
http://example.com/api/updateUser/1 //POST 更新标识为1用户信息
http://example.com/api/User/add //POST添加新的用户
规范后的RESTful风格的url,形式固定,可读性强,根据users名词和http动词就可以操作这些资源。名词可以使用驼峰命令或者"_"分割
http://example.com/api/users //GET 获取所有用户信息
http://example.com/api/users/1 //GET 获取标识为1用户信息
http://example.com/api/users/1 //DELETE 删除标识为1用户信息
http://example.com/api/users/1 //Patch 更新标识为1用户部分信息,包含在div中
http://example.com/api/users //POST 添加新的用户

统一返回数据格式

对于合法的请求应该返回统一的数据格式,对于返回数据,通常会包含如下字段。 
- code——即一个整数类型的HTTP响应状态码。 
- message——即返回给前端的信息,正常返回时是"success",当值为  "fail" 或  "error" 时,用于显示错误信息。
- data——即前端需要返回的数据。 当值为  "fail" 或  "error" 时,设置为null。
 
返回成功的响应json格式:
{
"code": 200,
"message": "success",
"data": {
"name": "小明",
"age": 16,
"sex": 0
}
}
返回失败的响应json格式:
{
"code": 401,
"message": "error message",
"data": null
}

 

http状态码

2**:成功–表示请求已被成功接收。
 
    200(成功)用浏览器打开一个网页,正常情况下都会返回200HTTP状态码。
 
    201(创建成功)代表资源创建成功
 
3**:重定向(URL跳转),要完成请求必须进行更进一步的操作。
 
    300(多种选择)下载一部片,服务器有 avi、mp4 等格式。
 
    301(永久移动)请求的网页已永久移动到新位置,自动将请求者转到新位置。
 
    304 (页面未修改) :按F5刷新(第二次访问)。
 
4**:客户端错误,请求有语法错误或请求无法实现。
 
    400(错误请求)服务器不理解请求的语法。
 
    401(未授权)没有携带认证信息或携带了错误的认证信息,而没有通过认证。(未登录时)
 
    403(禁止)携带了正确的认证信息,服务器认为该用户对该资源无权访问。(https输成了http)
 
    404(未找到)请求的内容不存在。
 
5**:服务器端错误,服务器未能实现合法的请求。
 
    500(服务器内部错误)服务器自己出现错误。
 
    502(网关错误)服务器作为网关或代理,从上游服务器收到无效响应。
 
    503(服务器不可用)服务器超载或停机维护不可用。
 

查询参数

在请求数据时,客户端经常会对数据进行过滤和分页等要求,而这些参数推荐采用HTTP Query Parameter的方式实现。
//搜索用户,最近登录
http://example.com/api/users?recently_login_day=3 //搜索用户,按照注册时间降序
http://example.com/api/users?sort=register_time_desc //搜索用户,按照注册时间升序、活跃度降序
http://example.com/api/users?sort=register_time_asc,liveness_desc

复杂参数

xxx

后端案例

GET请求

## url路径传参1
http://localhost:8080/api/user?id=1
后端要获取code参数,可以使用@RequestParam注解
 
## url路径参数2
http://localhost:8080/api/user/1
后端使用@PathVariable可以接收路径参数1。
 

POST请求

## Headers传值
 
在这里我们把Content-Type设置为了json格式。
我们还可以在headers里面加入别的参数,比如token
 
 
后端可以通过HttpServletRequest获取请求头的内容,如:
request.getHeader(string name)
request.getHeaders(String name)
request.getHeaderNames()
 
### Body传值
一般来说,使用json格式传值,如下图:
 
后端接受这种数据应该采用@RequestBody
@PostMapping(value = "/user")
public ApiResult addUser(@RequestBody UserDTO userDTO) {
return userService.add(userDTO);
}
 

RESTful api设计风格的更多相关文章

  1. RESTful API 设计风格

    HTTP常用动词 GET(SELECT):从服务器取出资源(一项或多项). POST(CREATE):在服务器新建一个资源. PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源). ...

  2. REST与RESTFul API最佳实践

    我经常会面试一些做PHP的开发者,让我很奇怪的是,10个人总有8个多不知道什么是REST服务,甚至是没有听说过.但RESTFul API已经是现在互联网里对外开放接口的主流模式,可参考: 豆瓣API  ...

  3. RESTful 良好的API设计风格

    1.使用名词而不是动词 Resource资源 GET读 POST创建 PUT修改 DELETE /cars 返回 cars集合 创建新的资源 批量更新cars 删除所有cars /cars/711 返 ...

  4. Restful API

    http://www.ruanyifeng.com/blog/2011/09/restful 参考资料:-------以网络为基础的应用软件的架构设计. Restful API的设计与实践 字数218 ...

  5. [转]10个有关RESTful API良好设计的最佳实践

    Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GE ...

  6. ASP.NET Core Web API 开发-RESTful API实现

    ASP.NET Core Web API 开发-RESTful API实现 REST 介绍: 符合REST设计风格的Web API称为RESTful API. 具象状态传输(英文:Representa ...

  7. 10个有关RESTful API良好设计的最佳实践

    Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GE ...

  8. **RESTful API版本控制策略

    做RESTful开放平台,一方面其API变动越少, 对API调用者越有利:另一方面,没有人可以预测未来,系统在发展的过程中,不可避免的需要添加新的资源,或者修改现有资源.因此,改动升级必不可少,但是, ...

  9. 10个有关RESTful API良好设计的最佳实践(转)

    原文地址:http://www.jdon.com/soa/10-best-practices-for-better-restful-api.html Web API已经在最近几年变成重要的话题,一个干 ...

随机推荐

  1. Leetocode7道买卖股票问题总结(121+122+123+188+309+901+714)

    题目1----121. 买卖股票的最佳时机I: 链接:https://leetcode-cn.com/problems/best-time-to-buy-and-sell-stock/ 给定一个数组, ...

  2. bookdown学习笔记

    主要参考大佬谢益辉的bookdown学习笔记 https://bookdown.org/yihui/bookdown/pandoc.html 灰常之详细 然后clone了他写好的小demo,准备自己试 ...

  3. [CF1304D] Shortest and Longest LIS - 贪心

    看样例,>><>><,要构造 LIS 最短的,我们需要找最小链划分的方案,即包含最少的下降列 很容易想到把连续 < 的看成一段,比如样例就是 .|.|. .| ...

  4. (转)HashMap和HashTable源码

    转自: http://www.cnblogs.com/ITtangtang/p/3948406.html http://frankfan915.iteye.com/blog/1152091 一.Has ...

  5. SAM的应用及例题

    专门开一个帖子记录一下自己在学习SAM时做的题,并总结一下做法 1.LCS https://www.cnblogs.com/wenci/p/10432932.html 这道题是要求对两个字符串查找最长 ...

  6. C编译过程

    system()调用系统命令 C语言源代码——> 预编译(1.去掉注释:2.包含文件)——> gcc -o a.o a.c 编译(编译成二进制质量)——> 链接系统库函数——> ...

  7. Docker学习(六)Dockerfile构建自定义镜像

    Docker学习(六)Dockerfile构建自定义镜像 前言 通过前面一篇文章可以知道怎么去使用一个镜像搭建服务,但是,如何构造自己的一个镜像呢,docker提供了dockerfile可以让我们自己 ...

  8. model_Flask

    虚拟环境 新建一个虚拟环境:mkvirtualenv 环境名 删除一个虚拟环境:rmvirtualenv 环境名 退出:deactivate win10下安装 1. 打开cmd 安装虚拟环境包 pip ...

  9. OpenGL 编程指南 (4)

    1.OpenGL用户裁剪需要使用一个vertex shader的内置变量gl_ClipDistance,它是一个声明的时没有指定大小的数组,因此需要重新声明它的大小或者将它作为一个编译时的常量使用(啥 ...

  10. Codeforces Round #602 (Div. 2, based on Technocup 2020 Elimination Round 3) B Box

    #include<bits/stdc++.h> using namespace std; ]; ]; int main() { int total; cin>>total; w ...