首页 > 其他分享> 文章详细

什么是 RESTful API

2022-07-21 20:37:40 阅读：221 来源： 互联网

标签：body HTTP GET URL 什么 API PUT RESTful method

简要定义

RESTful 设计风格，简而言之，就是用 HTTP method 表示操作，URL 表示被操作的资源的一种 HTTP API 设计风格。

这其中，GET 表示获取（查询），POST 表示创建，PUT 表示修改，DELETE 表示删除。

为什么将 API 设计成 RESTful 风格

清晰，标准，简明，扩展方便，可维护性好。

拆解

REST，（Resource）Representational State Transfer，即“（资源的）表现层状态转移”。

我们上网（通过浏览器）或通过 HTTP Client 和服务器交互，都是在操作服务器上的资源（resource）。

但资源我们很难直接操作，也不安全。例如，我们不大可能直接去服务器的数据库改数据，也不大可能去服务器的存储中改文件，而是经过一个表现层（JSON、XML 等）并通过 HTTP 动词来操作。

HTTP 动词表示动作；URL 定位到资源（这意味着，URL 一般只出现名词）；请求体（request body）和响应体（response body）以某种格式表现资源。

这就是 REST 的大致含义。

REST 的一般最佳实践

URL

全用小写字母，用横线（-）分隔，通常只出现名词。

正例：

修改某个作者下的某个文章

PUT /api/author/3/article/33112

查看某项目下的流水线列表，第 1 页，每页 30 个

GET /api/project/<project_id>/pipelines?page_size=30&page_no=1

反例：

@RequestMapping("/getTotalElectricityForIntervalDays")

直接把函数名一抄，既未明确 method，又不是 REST 风格。

method

动词按照语义对应到操作。GET 查，POST 增，DELETE 删，PUT 和 PATCH 改。

HEAD、GET 须安全、幂等、无副作用。所以，GET 用来表示纯读操作，不应使用 GET 表示增、删、改。

PUT、PATCH 须幂等。而 PUT 和 PATCH 的区别是，PUT 表示修改一个资源的整体，PATCH 表示修改一个资源的部分字段。

如果 method 无法表达出相应的动作，则 method 用 POST，动作可以在 URL 中体现，例如：

POST /api/foo/3/bar/_search

这里的动作前面加了下划线，因为 search 不是资源，所以特殊化处理。

如果某个动作在软件中使用非常频繁，可以考虑自定义 method。

HTTP header

正确使用状态码，发挥其本身的含义，而不是一股脑使用 200、400、500。

例如：

200 表示一般成功；

201 表示已创建；

202 表示接受了某个命令（异步执行）；

419 表示触发了限流；

……

HTTP body

response body 收到即用，无需拆箱。描述性的信息放在 header。

正例：

header

X-Code: 0
X-Message: ok

body

{
    "foo": "qwer",
    "bar": 33
}

反例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "foo": "qwer",
        "bar": 33
    }
}

标签：body,HTTP,GET,URL,什么,API,PUT,RESTful,method
来源： https://www.cnblogs.com/jthmath/p/16503458.html

本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；
2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；
3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；
4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；
5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

ICode9