从Google的开源框架看Restful API 设计

restful是一种api 风格，为什么要使用restful api？道理很简单，就是为了使api 更易用，更容易拓展。没有restful 之前，各种api 风格群魔乱舞，有了restful 之后，似乎成了一种潮流，各家大公司都默默遵守着restful api 的设计规范，就好像你的api 不是restful风格的，你都不好意思和别人打招呼。

什么样是好的restful api，可能光说理论大家很难理解。这里我们从google 的开源框架kubernetes 看一下google对restful api的理解。

首先是get 请求。在restful api 中，每一个路径都对应着一种资源。http 的几种请求post，delete，

put，get 分别对应着对资源的增删改查。

GET 获取资源

首先是get 请求，很容易理解，就是获取相关的数据，如上get /api/v1 获取的是api 的相关列表。

如果获取的数据是集合，就用复数的形式表示。比如

既然路径对应着资源，那么如何设计请求参数呐？比如 /users 获取的是人的列表，如果想获取32 岁的人的列表改如何设计呐？

对于请求的参数分为三种，这里get 在restful 中，应该只使用其中两种。比如

在url 中的参数称为pathParameter 路径参数。没显示在url 中的，叫请求参数，比如上面的pretty，我们使用get 请求的时候是这样的：

get /api/v1/namespaces/coutomes/pods?pretty=true

举个栗子，get /stars/{star}/persons 获取某某星人的数据

如果要获取地球人的数据 get /starts/earth/persons

获取地球上男人的数据 get /starts/earth/persons？gender=male

把star 设置为路径参数，是因为star 是标识我们资源，也就是person 的位置参数。而性别gender 设置为请求参数，是因为性别是person 的一种属性。

DELETE 删除资源

delete 与get 的设计类似，不过delete 代表的语义是删除。一般delete 的请求都是和删除数据相关的。比如删除3年二班王小明的数据

delete /3/2/wangxiaoming

POST PUT PATCH

着三种请求放在一起，因为他们的api 设计是相同的。不同的http 语义。比如post 代表创建，create。put 代表着更新，替换。patch 就是补丁，也就是部分更新。

比如，我创建一篇博客，就该使用post。修改博客的正文内容，就使用put。至于patch 方法，我们一般是不用的，因为很多web 容器不支持。但是google 毕竟是大公司，k8s使用patch 请求的。通常情况下，有post 和put 就完全够用了。其实过去的api，连put 和delete 也不用，就用get 和post 就够了。

post ，put，和patch 和get方法最明显的区别是，post，put，patch是多一个参数的，这个参数不显示在url 路径中，称为请求体。requestbody。

这种请求，我们可以通过工具模拟。比如我想创建3年二班王小明的数据。就可以这样

这里就是一个post 请求。请求参数为json 数据。这样就创建了一个person 的数据。名字是王小明，father 是王大明。当我们想修改数据时，比如发现，小明的爸爸其实是隔壁老王。这时，我们的请求就是

就是这样。下篇，我们使用springmvc 具体实现一个restful api。喜欢的可以关注一下，欢迎沟通交流。不喜欢的也可以关注一下。