RESTful API 设计实践 我不是女神ヾ 2021-09-21 19:16 342阅读 0赞 RESTful是目前流行的API设计规范,遵守这套规范设计出的API可以较好的适用不同类型的客户端,例如:PC/Mobile/Pad… [RESTful][] 表现层状态转换(英语:Representational State Transfer,缩写:REST)是Roy Thomas Fielding博士于2000年在他的博士论文\[1\]中提出来的一种万维网软件架构风格,目的是便于不同软件/程序在网络(例如互联网)中互相传递信息。 ### RESTFul 使用的协议 ### API内容的传输总是基于[HTTP协议][HTTP]。 在线上产品通常使用安全的HTTP协议,即HTTPS。 ### 域名及API版本 ### 如果这套API是提供第三方服务的,通常要用单独的域名。如果项目不专注于第三方服务或中小型项目可以在域名后加 `api` 来标识。 // 单独域名 http://api.domain.com // 中小型项目,前后端共用域名 http://domain.com/api 版本号通常以v1/v2来标识,默认第一版不加路径中不加v1,当接口有新版本后加版本标识,例如第二版API可以为: http://api.domain.com/v2 http://domain.com/api/v2 如果只有部分接口出现第二版,如果第二版的user接口,通常只在 `/users` 后加版本号。 //之前版本 api/users/analysis //第二版 analysis 接口 api/users/v2/analysis ### 路径 (Endpoint) ### 访问一个API要有一个确定的地址,这个地址即路径(Endpoint)。 在RESTful中每个路径都表示一个资源,这个资源可以是音视频、图片、文本(XML/JSON)。通常接口返回的是JSON数据,如一个用户的信息、一个用户列表。 接口的地址通常使用名词复数,表示这个资源的集合(Collection),例如关于用户的接口可能是这样的开头 `/api/users`,关于图片相关的接口 `/api/photos`,以上这些路径标识了这套API中某类资源。 在设计RESTful API时可以把这些路径想象为一个树形分支,可以把 `api` 当做根路径,之后的名词(users、photos)是跟节点(api)的分支,如果做成脑图它是这样的。 ![image.png][] 在操作系统中(win、unix、linux)文件都是按目录组织的,这些目录都是树型(在unix/linux及其明显),访问一个文件都是一个具体的目录加上一个文件名,API接口区分不同资源也是这种方式。 #### 集合中的某个对象的具体操作 #### 常见CRUD操作通过HTTP动词区分,针对具体的某个对象操作在其集合(users、photos)加id然后在拼接上操作名称。 查询、修改某个用户(id:123)的信息。 // 123为用户id GET /api/users/123 PUT /api/user/123 按照process本身的属性进行筛选对process进行筛选;获取process流程相关的表单相关的数据。 // 通常使用查询字符串(Query Param), 123为process记录(对象)的id GET /api/processes/123?categories=1 // process的表单相关操作 - 获取其表单数据 GET /api/processes/123/form-data // process的表单相关操作 - 删除其表单数据 DELETE /api/processes/123/form-data // process的表单相关操作 - 对该表单数据进行分析操作 GET /api/processes/123/form-data/analysis 通过以上API路径可以形成如下树型脑图: ![image.png][image.png 1] #### 互联网公司是如何使用的 #### 这里以Github为例,Github开放API接口: https://api.github.com,下面是整理后的接口。 // 用户相关操作接口1 -- 用户其他信息 "current_user_url": "https://api.github.com/user", "emails_url": "https://api.github.com/user/emails", "followers_url": "https://api.github.com/user/followers", "following_url": "https://api.github.com/user/following{/target}", "keys_url": "https://api.github.com/user/keys", "starred_url": "https://api.github.com/user/starred{/owner}{/repo}", "user_org_url": "https://api.github.com/user/orgs", "cur_user_repos_url": "https://api.github.com/user/repos{?type,page,per_page,sort}", // 用户相关操作接口2 -- 对用户表相关的操作 "user_url": "https://api.github.com/users/{user}", "user_repos_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}", //搜索接口 -- 各种类别的搜索 "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}", "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}", "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}", "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}", "label_search_url": "https://api.github.com/search/labels?q={query}&repository_id={repository_id}{&page,per_page}", "repos_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}", // 组织操作接口 "org_url": "https://api.github.com/orgs/{org}", "org_repos_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}", "organization_teams_url": "https://api.github.com/orgs/{org}/teams" 总结: * 使用路径变量(Path Value)使接口很有层次感 * 接口清晰易懂,一看就了解接口的作用 #### 路径命令规范 #### * 通常常在路径中使用名词复数表示一类资源,如:users、photos * 路径中的动词通常要变成名词,通常可在动词后加 `ing`,如:api/processes/publishing * 如果路径中存在多个单词,中间使用 “-” 号分隔,如:api/processes/123/form-data * 避免多级URL,不利于扩展 * bad:`GET api/users/123/type/2` * good: `GET api/users/123?type=2` 错误的路径命名: * /user/getAllUsers * /user/createNewUser * /user/deleteUser ### HTTP 动词 ### RESTful API 的一大特点是使用HTTP动词来区分资源集合(users,photos,departments)的CRUD,并且有不同的状态码, 这些是常用的动词。 * GET 请求用于查询(Read) * POST 请求用于新增(Create) * PUT 请求用于修改(Update) * DELETE 请求用于删除(Delete) * PATCH 更新(Update),通常是部分更新,不常用 #### 动词返回状态码 #### 这些返回值,与 `200` 状态码的含义密切相关。 虽然 `201` `204` 都表示成功,但开发业务中通常都用 `200` 这个状态码表示。 * GET: 200 OK * POST: 201 Created * PUT: 200 OK * DELETE: 204 No Content * PATCH: 200 OK ### 状态码 ### 客户端每次请求,服务器都必须给出响应。响应分为两个部分:状态码和数据。 每次响应应严格遵守HTTP状态码,这样便于服务端和浏览器的交互。 状态码分类: * 1xx:相关信息 * 2xx:操作成功 * 3xx:重定向 * 4xx:客户端错误 * 5xx:服务器错误 [详细HTTP状态码][HTTP 1] ##### 业务中常用状态码 ##### <table> <thead> <tr> <th>状态码(status)</th> <th>说明</th> <th>备注</th> </tr> </thead> <tbody> <tr> <td>200</td> <td>正常</td> <td></td> </tr> <tr> <td>401</td> <td>未登录</td> <td></td> </tr> <tr> <td>403</td> <td>权限不足</td> <td></td> </tr> <tr> <td>404</td> <td>访问资源不存在</td> <td></td> </tr> <tr> <td>500</td> <td>不可控的服务器异常</td> <td>可控制的业务逻辑异常使用code代表</td> </tr> </tbody> </table> ### 服务端响应 ### 服务端响应另一部分是数据。数据可是xml、json格式,如果是图片、视频文件在响应体中是二进制数据。 通常在RESTful API接口是以JSON格式数据交互的,因此客户端HTTP的请求头(header)中应携带 `Accept` 为 `application/json`,同时服务端响应应携带 `Content-Type` 为 `application/json`。下面是一个例子。 // Rquest GET /api/user/123 HTTP/1.1 Accept: application/json // Response HTTP/1.1 200 OK { "code":200, "message":"OK", "data":{} } ### 服务端响应体封装 ### 因为业务的复杂性,HTTP状态码并不能完全标识特殊业务信息,因此在业务响应体中通常带有 `code` 标识业务状态码,业务状态码基于HTTP状态码扩展。 常见的响应体封装如下: { "code":200, "message":"OK", "data":{} } #### 服务端提供接口使用信息 #### API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。 api.github.com 就是一个很好的实践。用户只要访问这个接口就可得到接口信息。 #### 一些实践 #### * 如果一个接口返回数据包含一组图片或视频,那么这些数据应该以完整的URL形式返回,而不是只有名字 * 一个好用的API在抛出业务异常是通常给出这个错误异常的QA链接 ### 参考资料、其他资料 ### * [表现层状态转换 Wikipedia][Wikipedia] * [Web API design][] * [RESTful API 设计指南 阮一峰][RESTful API _] * [RESTful API 最佳实践 阮一峰][RESTful API _ 1] [RESTful]: https://zh.wikipedia.org/wiki/%E8%A1%A8%E7%8E%B0%E5%B1%82%E7%8A%B6%E6%80%81%E8%BD%AC%E6%8D%A2 [HTTP]: https://zh.wikipedia.org/wiki/%E8%B6%85%E6%96%87%E6%9C%AC%E4%BC%A0%E8%BE%93%E5%8D%8F%E8%AE%AE [image.png]: /images/20210920/2397377f95c84e9b831a846283117f33.png [image.png 1]: /images/20210920/ce8319fa24b84abcbf359add56732ccc.png [HTTP 1]: https://zh.wikipedia.org/wiki/HTTP%E7%8A%B6%E6%80%81%E7%A0%81 [Wikipedia]: https://zh.wikipedia.org/wiki/REST [Web API design]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design [RESTful API _]: http://www.ruanyifeng.com/blog/2014/05/restful_api.html [RESTful API _ 1]: http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html
相关 Java RESTful API设计误区:实践指导 在设计和开发Java RESTful API时,可能会遇到一些误区。以下是一些常见的误区及实践指导: 1. **过于复杂的设计**: - 误区:过度封装、参数过多。 淡淡的烟草味﹌/ 2024年09月11日 23:33/ 0 赞/ 7 阅读
相关 【最佳实践】如何设计 RESTful API ? 良好的 API 设计是一个经常被提及的话题,特别是对于那些试图完善其 API 策略的团队来说。一个设计良好的 API 的好处包括:改进开发者体验、更快速地编写文档以及更高效地推 一时失言乱红尘/ 2024年03月16日 16:31/ 0 赞/ 16 阅读
相关 [译] RESTful API 设计最佳实践 [https://juejin.im/entry/6844903503953920007][https_juejin.im_entry_6844903503953920007 一时失言乱红尘/ 2022年12月10日 14:57/ 0 赞/ 217 阅读
相关 RESTful API 设计最佳实践 背景 目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权? 我就是我/ 2022年09月25日 09:26/ 0 赞/ 236 阅读
相关 RESTful API 设计最佳实践 参考[http://www.cnblogs.com/shanyou/category/307401.html][http_www.cnblogs.com_shanyou_cat 拼搏现实的明天。/ 2022年09月19日 01:56/ 0 赞/ 234 阅读
相关 RESTful API 设计最佳实践 本文由 [伯乐在线][Link 1] \- [bruce-accumulate][] 翻译。未经许可,禁止转载! 英文出处: [Vinay Sahni][]。欢迎加入 [ 缺乏、安全感/ 2022年08月19日 15:08/ 0 赞/ 197 阅读
相关 RESTful API 设计最佳实践 原文地址:http://blog.jobbole.com/41233/ 背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ” ゝ一世哀愁。/ 2022年06月17日 09:06/ 0 赞/ 210 阅读
相关 RESTful API实践 RESTful介绍 RESTful相关介绍请参考: [https://www.runoob.com/w3cnote/restful-architecture.ht ゞ 浴缸里的玫瑰/ 2022年05月15日 12:51/ 0 赞/ 229 阅读
相关 RESTful API 设计实践 RESTful是目前流行的API设计规范,遵守这套规范设计出的API可以较好的适用不同类型的客户端,例如:PC/Mobile/Pad… [RESTful][] 表现层状态转换 我不是女神ヾ/ 2021年09月21日 19:16/ 0 赞/ 343 阅读
还没有评论,来说两句吧...