正文
如何设计出优秀的Restful API？
提示：扫一扫查出行【扫一扫了解最新限行尾号】
复制提示
https://mp.weixin.qq.com/s?__biz=MzU0OTE4MzYzMw==&mid=2247485240&idx=1&sn=b5b9c8c41659d2457282dc7ff54d992e&chksm=fbb28ec6ccc507d0951dc50f1a3ecb2529ab39493293e24139ff28cfcde5f8190fa0598b3641&scene=0&key=f9325dcb38245ddc50a7a927757f2643064b68083481a87914c2e39eaa9d4c359ff6b5e8d4f6a29c50fb7bb0145a45ddc01a770d4bc4a884c8e38b66480ad9b0b7a79b21e7fdcbaae57ee4ee366d9a7f&ascene=1&uin=MjgwMTEwNDQxNg%3D%3D&devicetype=Windows-QQBrowser&version=6103000b&lang=zh_CN&pass_ticket=TQe4Haub6SqYOe6NAx8gRfTg7k5UKFKeGcGwRzqGtzjDX%2Bt%2F5w3wOtRKNju9ZHpe
原创： 帝都羊 架构师小秘圈 昨天
1 你一直在错误的使用http协议
现在微服务真是火的一塌糊涂！大街小巷，逢人必谈微服务，各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务！而作为微服务之间通信的桥梁，Web API的设计就显得非常重要。
Http是目前互联网使用最多的协议，没有之一！但是作为Http协议创始人之一的Roy Fielding认为，过去十年，大家都在错误的使用Http协议。删除一个数据，路径往往是 delete/{id} , 更新一条数据，路径往往被定义为update/{id}。你已经被Roy在心里默默的鄙视了！
Roy Fielding提出了一种用于设计Web服务的架构方法，称为Representational State Transfer（REST）。REST的概念是将API结构分离为操作和资源。使用HTTP方法GET、DELETE、POST和PUT操作资源。
设计糟糕的REST API = 浪费时间！
优秀的API就像一位艺术家在舞台上表演，其用户就是观众，能给所有人带来赏心悦目的美感！
2 REST API里面的术语
Resource（资源）
是指代表某种东西的对象，它具有一些与之相关的数据，并且可以有一组方法对其进行操作。 例如。 学校，班级和学生是资源，删除，添加，更新是要对这些资源执行的操作。
Collections（集合）
是一组资源，例如，211大学是全国211所优质大学的集合。
URL（统一资源定位符）
是可以通过其定位资源的路径，并且可以对其执行某些操作。
3 API设计使用名词，而不是动词
例如获取所有学生，可能通过如下api:
/getAllStudents,
增加学生，可能是：/addNewStudent
更新学生，可能是：/updateStudent
删除学生，可能是：/deleteStudent
删除所有学生，可能是：/deleteStudents
获取三好学生，可能是：/getSanHaoStudents
更多操作......等等。
对于不同的操作，会衍生出越来越多的API接口，数量不停的增多，接口将会变得混乱和难以维护。
有没有感觉哪里不对？
URL应仅包含资源（名词）而不包含动作或者动词！增加学生的API路径：/addNewStudent，包含操作addNew以及资源名称Student。
正确的方法是什么？
/schools ，是一个很好的例子，不包含任何动作。但是我们怎么告诉服务器，有关学校资源的操作呢，例如增加，删除或者更新学校？
这就是HTTP方法(GET,POST,DELETE,PUT)(也成为动词)扮角色的地方！API接口的资源应始终为复数，如果我们要访问资源的一个实例，我们可以在URL中传递id或者name之类的。
GET 路径 /schools 获取所有的学校
GET 路径 /schools/清华 获取名字叫清华大学的详细信息
DELETE 路径 /schools/清华 从学校列表中，删除清华大学
资源和资源之间可能有父子关系，那又应该如何设计呢？例如学校的学生，下面是一些示例：
GET /schools/清华/students 获取清华大学的所有学生
GET /schools/清华/students/张三 获取清华大学名字叫张三的学生的详细信息
DELETE /schools/清华/students/张三 删除清华大学名字叫张三的学生
4 合理利用Http本身的方法
HTTP已定义了几组方法，这些方法指示要对资源执行什么类型的操作。我们制定web接口，要合理利用http的方法！
URL是说白了，就是一个句子，其中资源是名词，HTTP方法是动词。
GET 方法
从资源请求数据，不应产生任何其他作用。
例如/schools/清华/students，返回所有清华大学的学生
POST方法
请求服务器在数据库中创建资源，主要是在提交Web表单时。
/schools/清华/students/张三，在清华大学的学生资源，新增一个张三的学生。
POST是非幂等的，这意味着多个请求将具有不同的效果。
PUT方法
请求服务器更新资源或创建资源（如果不存在）。
/schools/清华/students/张三， 对清华大学下的学生资源中，更新或者创建张三。
PUT是幂等的，这意味着多个请求将具有相同的效果。
DELETE方法
请求从数据库中删除资源或其实例。
/schools/清华/students/张三，从清华大学的学生集合中，删除学生张三的资源。
5 使用JSON作为通信格式
JSON阅读性更高，扩展性更强，适合各种环境和语言进行解析，现在大的互联网公司，对外提供的API基本都使用JSON。
6 使用HTTP状态码
当客户端通过API向服务器发出请求时，客户端应该知道反馈，无论是失败，成功还是请求错误。 HTTP状态代码是一系列标准化代码，针对http请求的可能会发生的各种情况。 服务器应始终返回正确的状态代码。
很多人喜欢把错误信息放在返回值中，典型的Code和Message，其实比较Low。
下面是Http状态码，可以合理利用处理各种请求反馈，将http自身的错误和服务器内部的错误，有一个很好的区分。
2xx(成功类别)
200 Ok表示GET，PUT或POST成功的标准HTTP响应。
201 Created每当创建新实例时，都应返回此状态代码。 例如，使用POST方法创建新实例时，应始返回201状态代码。
204 No Content表示请求已成功处理，但未返回任何内容。
3xx（重定向类别）
304 Not Modified表示客户端已在其缓存中有响应。 因此无需再次传输相同的数据。
4xx（客户端错误类别）
这些状态代码表示客户端已提出错误请求。
400 Bad Request表示未处理客户端的请求，因为服务器无法理解客户端要求的内容。
401 Unauthorized表示不允许客户端访问资源，并应使用所需凭据重新请求。
403 Forbidden表示请求有效且客户端已通过身份验证，但不允许客户端出于任何原因访问该页面或资源。例如，有时不允许授权客户端访问服务器上的目录。
404 Not Found表示请求的资源现在不可用。
410 Gone表示已移动的请求资源不再可用。
5xx（服务器错误类别）
500内部服务器错误表示请求有效，但服务器完全混淆，并要求服务器提供某些意外情况。
503 Service Unavailable表示服务器已关闭或无法接收和处理请求。大多数情况下，例如服务器正在进行维护。
7 搜索，排序，过滤和分页
所有这些操作都只是对一个数据集的查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。
下面看几个例子：
GET /schools ? search = 清华大学 在大学集合中，搜索清华大学
GET /schools ? sort = rank_asc 按照升序排列学校
GET /schools ? location = 北京 按照城市对学校过滤
GET /schools ? page=6 获取第六页的学校列表
8 使用版本控制
例如下面两个版本地址：
http://api.yourservice.com/v1/schools/清华
http://api.yourservice.com/v2/schools/清华
在API上加入版本信息可以有效的使用户访问正确的API，v2是新开发功能，开发阶段，让所有用户访问v1，等开发完成统一切到v2。
可以有效的跨版本访问，例如在v2版本，还需要访问v1版本的一些接口
9 总结
1，API接口都用小写
2，使用JSON通信
3，API带版本控制，比如v1,v2
4，使用Token令牌进行鉴权
5，路径中单词连接使用中划线-
6，使用HTTP自身的方法表示增删改查资源， GET：查询，POST：新增，PUT：更新，DELETE：删除
7，合理使用HTTP状态码，200，201，400，401，403，500。比如401表示用户身份认证失败，403表示你验证身份通过了，但是无权限操作资源。
在此，祝大家设计出优秀的Restful API！
现在微服务真是火的一塌糊涂！大街小巷，逢人必谈微服务，各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务！而作为微服务之间通信的桥梁，Web API的设计就显得非常重要。
Http是目前互联网使用最多的协议，没有之一！但是作为Http协议创始人之一的Roy Fielding认为，过去十年，大家都在错误的使用Http协议。删除一个数据，路径往往是 delete/{id} , 更新一条数据，路径往往被定义为update/{id}。你已经被Roy在心里默默的鄙视了！
Roy Fielding提出了一种用于设计Web服务的架构方法，称为Representational State Transfer（REST）。REST的概念是将API结构分离为操作和资源。使用HTTP方法GET、DELETE、POST和PUT操作资源。
设计糟糕的REST API = 浪费时间！
优秀的API就像一位艺术家在舞台上表演，其用户就是观众，能给所有人带来赏心悦目的美感！
2 REST API里面的术语
Resource（资源） 是指代表某种东西的对象，它具有一些与之相关的数据，并且可以有一组方法对其进行操作。 例如。 学校，班级和学生是资源，删除，添加，更新是要对这些资源执行的操作。
Collections（集合） 是一组资源，例如，211大学是全国211所优质大学的集合。
URL（统一资源定位符） 是可以通过其定位资源的路径，并且可以对其执行某些操作。
3 API设计使用名词，而不是动词
例如获取所有学生，可能通过如下api:
/getAllStudents,
增加学生，可能是：/addNewStudent
更新学生，可能是：/updateStudent
删除学生，可能是：/deleteStudent
删除所有学生，可能是：/deleteStudents
获取三好学生，可能是：/getSanHaoStudents
更多操作......等等。
对于不同的操作，会衍生出越来越多的API接口，数量不停的增多，接口将会变得混乱和难以维护。
有没有感觉哪里不对？
URL应仅包含资源（名词）而不包含动作或者动词！增加学生的API路径：/addNewStudent，包含操作addNew以及资源名称Student。
正确的方法是什么？
/schools ，是一个很好的例子，不包含任何动作。但是我们怎么告诉服务器，有关学校资源的操作呢，例如增加，删除或者更新学校？
这就是HTTP方法(GET,POST,DELETE,PUT)(也成为动词)扮角色的地方！API接口的资源应始终为复数，如果我们要访问资源的一个实例，我们可以在URL中传递id或者name之类的。
GET 路径 /schools 获取所有的学校
GET 路径 /schools/清华 获取名字叫清华大学的详细信息
DELETE 路径 /schools/清华 从学校列表中，删除清华大学
资源和资源之间可能有父子关系，那又应该如何设计呢？例如学校的学生，下面是一些示例：
GET /schools/清华/students 获取清华大学的所有学生
GET /schools/清华/students/张三 获取清华大学名字叫张三的学生的详细信息
DELETE /schools/清华/students/张三 删除清华大学名字叫张三的学生
4 合理利用Http本身的方法
HTTP已定义了几组方法，这些方法指示要对资源执行什么类型的操作。我们制定web接口，要合理利用http的方法！
URL是说白了，就是一个句子，其中资源是名词，HTTP方法是动词。
GET 方法 从资源请求数据，不应产生任何其他作用。
例如/schools/清华/students，返回所有清华大学的学生
POST方法 请求服务器在数据库中创建资源，主要是在提交Web表单时。
/schools/清华/students/张三，在清华大学的学生资源，新增一个张三的学生。
POST是非幂等的，这意味着多个请求将具有不同的效果。
PUT方法 请求服务器更新资源或创建资源（如果不存在）。
/schools/清华/students/张三， 对清华大学下的学生资源中，更新或者创建张三。
PUT是幂等的，这意味着多个请求将具有相同的效果。
DELETE方法 请求从数据库中删除资源或其实例。
/schools/清华/students/张三，从清华大学的学生集合中，删除学生张三的资源。
5 使用JSON作为通信格式
JSON阅读性更高，扩展性更强，适合各种环境和语言进行解析，现在大的互联网公司，对外提供的API基本都使用JSON。
6 使用HTTP状态码
当客户端通过API向服务器发出请求时，客户端应该知道反馈，无论是失败，成功还是请求错误。 HTTP状态代码是一系列标准化代码，针对http请求的可能会发生的各种情况。 服务器应始终返回正确的状态代码。
很多人喜欢把错误信息放在返回值中，典型的Code和Message，其实比较Low。
下面是Http状态码，可以合理利用处理各种请求反馈，将http自身的错误和服务器内部的错误，有一个很好的区分。
2xx(成功类别)
200 Ok表示GET，PUT或POST成功的标准HTTP响应。
201 Created每当创建新实例时，都应返回此状态代码。 例如，使用POST方法创建新实例时，应始返回201状态代码。
204 No Content表示请求已成功处理，但未返回任何内容。
3xx（重定向类别）
304 Not Modified表示客户端已在其缓存中有响应。 因此无需再次传输相同的数据。
4xx（客户端错误类别）
这些状态代码表示客户端已提出错误请求。
400 Bad Request表示未处理客户端的请求，因为服务器无法理解客户端要求的内容。
401 Unauthorized表示不允许客户端访问资源，并应使用所需凭据重新请求。
403 Forbidden表示请求有效且客户端已通过身份验证，但不允许客户端出于任何原因访问该页面或资源。例如，有时不允许授权客户端访问服务器上的目录。
404 Not Found表示请求的资源现在不可用。
410 Gone表示已移动的请求资源不再可用。
5xx（服务器错误类别）
500内部服务器错误表示请求有效，但服务器完全混淆，并要求服务器提供某些意外情况。
503 Service Unavailable表示服务器已关闭或无法接收和处理请求。大多数情况下，例如服务器正在进行维护。
7 搜索，排序，过滤和分页
所有这些操作都只是对一个数据集的查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。
下面看几个例子：
GET /schools ? search = 清华大学 在大学集合中，搜索清华大学
GET /schools ? sort = rank_asc 按照升序排列学校
GET /schools ? location = 北京 按照城市对学校过滤
GET /schools ? page=6 获取第六页的学校列表
8 使用版本控制
例如下面两个版本地址：
http://api.yourservice.com/v1/schools/清华
http://api.yourservice.com/v2/schools/清华
在API上加入版本信息可以有效的使用户访问正确的API，v2是新开发功能，开发阶段，让所有用户访问v1，等开发完成统一切到v2。
可以有效的跨版本访问，例如在v2版本，还需要访问v1版本的一些接口
9 总结
1，API接口都用小写
2，使用JSON通信
3，API带版本控制，比如v1,v2
4，使用Token令牌进行鉴权
5，路径中单词连接使用中划线-
6，使用HTTP自身的方法表示增删改查资源， GET：查询，POST：新增，PUT：更新，DELETE：删除
7，合理使用HTTP状态码，200，201，400，401，403，500。比如401表示用户身份认证失败，403表示你验证身份通过了，但是无权限操作资源。
在此，祝大家设计出优秀的Restful API！
