5 个基本的 REST API 设计指导方针 怼烎@ 2022-07-14 13:14 126阅读 0赞 当我们开始从事API开发的时候,设计问题便出现了. 一个强而有力的API设计方法是API成功的关键要素. 设计糟糕的API会导致API滥用问题,或者更糟:API根本没人使用 (指Web开发者). 建立和提供一个艺术品级别的API需要考虑一下几点: * 使用如部分资料中所描述的RESTful API原则 ([Roy Fielding][], [Martin Fowler][], HTTP 规范等). * 参考Web巨头的做法,例如Google, Microsoft, Facebook, PayPal 和其他大公司. 关于如何设计一个REST 风格的API这个问题,目前没有通用答案. 而REST 风格的最佳实践这个问题仍然处于辩论和巩固中,这就是为什么这项工作很迷人的原因. 第 1 段(可获 1.51 积分) 0 ![102730_OdG2_35.jpg][] lison2个月前 ### URI 命名 ### 涉及到给项目中的资源明明时,有三种主要的命名约定方式: 驼峰命名法(CamelCase), 蛇形命名法(snake\_case), 和 脊柱形命名法(spinal-case). 这些命名法则类似于我们使用的自然语言,他们只是一种命名资源的方式,使用他们时要避免引入空格,撇号等特殊字符. 这些法则在编程语言中很通用,因为他们只使用一组有限的特性为变量命名. ### 驼峰命名法(CamelCase) ### 驼峰命名法在Java语言中很流行 !?. 它将每个单词的首字母大写,例如 camelCase, currentUser,等. 抛弃对这种命名法的可读性的争议,它主要的缺点是在大小写不敏感的上下文中这种方式命名的不同变量来讲是无效的(有些语言是忽略大小写的,例如T-SQL的变量声明). 第 3 段(可获 1.41 积分) 0 ![102730_OdG2_35.jpg][] lison2个月前 根据文档 RFC3986 规定, URL是大小写敏感的 (除了主机头等信息). 实际情况中,大小写敏感问题可能会对在Windows环境托管的API导致出现问题. 所以建议使用脊柱命名法(spinal-case) ( RFC3986 文档中突出强调了这一点), 这种命名法也被 Google, PayPal 和其他大公司使用. ![REST API Guidelines][] ## 2. HTTP 方法 ## 如前所述, 建立一个REST风格的API 的主要关键目标之一是使用HTTP协议作为应用程序的协议,从而避免制作出“土造”的REST风格API(好难翻). 因此, 我们应当系统的使用HTTP谓词来描述对资源所要执行的操作,并且让开发人员可以方便的处理重复的CRUD操作. 第 5 段(可获 1.35 积分) 0 ![113050_sz7y_35.jpg][] learner2个月前 ### OPTIONS ### 描述目标资源的通信参数. ## 3. HTTP头 ## HTTP头的字段提供了有关请求或应答必要的信息,或者提供了有关消息体重发送的对象的信息. HTTP消息头有4种类型: 1. 一般头: 这些头的字段对请求和响应消息有通用性. 2. 客户端请求头: 这些头的字段只能应用于请求消息. 3. 服务器响应头: 这些头的字段只能应用于响应消息. 4. 实体头:这些头的字段定义了有关实体正文的元信息,如果这儿没有正文,则定义有关请求确认的资源的元信息 第 7 段(可获 1.28 积分) 0 ![134004_ico2_35.jpg][] KeYIKeYI2天前 ### 排序 ### 排序是指在集合资源上的查询结果进行排序.排序参数需要包含进行排序的字段的名字,并以逗号隔开. ### 搜索 ### 搜索是一个集合的子资源.因此,搜索的结果有与资源和集合本身不同的格式.这使得我们可以添加建议,修正和与该搜索相关的其他信息.搜索提供参数的方式与过滤相同----都是通过查询参数,但是搜索参数不需要精确的值,并且搜索参数的语言允许近似匹配. 第 9 段(可获 1.2 积分) 0 ![102730_OdG2_35.jpg][] lison2个月前 403 – FORBIDDEN: 拒绝访问. 404 – NOT FOUND: 找不到文件. 500 – INTERNAL SERVER ERROR: API 开发者应当避免这种错误. 如果这种错误在全局异常中被捕获, stack trace会记录下这个错误并且不会返回响应内容. ## 总结 ## REST 不是个新事物. REST 是大型应用服务器所用各式各样获取数据方式的一种回归, 通过它来强调早期的Internet,URI标准和HTTP标准(返璞归真,阿弥陀佛). 资源建模(指REST风格API设计)需要基于业务需求做仔细考虑, 技术开发注意事项(纯粹的架构设计,可维护性等)和成本效益分析等前面已经讨论过的各种各样的方法,通过做这些以便创造出更加易于用户体验的API. [Roy Fielding]: https://en.wikipedia.org/wiki/Roy_Fielding [Martin Fowler]: https://en.wikipedia.org/wiki/Martin_Fowler [102730_OdG2_35.jpg]: https://coyee.com/uploads/user/20161009/102730_OdG2_35.jpg [REST API Guidelines]: https://coyee.com/uploads/img/20161004/204605_8NEJ.png [113050_sz7y_35.jpg]: https://coyee.com/uploads/user/20160917/113050_sz7y_35.jpg [134004_ico2_35.jpg]: https://coyee.com/uploads/user/20161019/134004_ico2_35.jpg
相关 Java RESTful API设计误区:实践指导 在设计和开发Java RESTful API时,可能会遇到一些误区。以下是一些常见的误区及实践指导: 1. **过于复杂的设计**: - 误区:过度封装、参数过多。 淡淡的烟草味﹌/ 2024年09月11日 23:33/ 0 赞/ 45 阅读
相关 网络通讯选择TCP或UDP的指导方针 ![20160706175025022][] ![20160706175034631][] [20160706175025022]: /images/2022072 Love The Way You Lie/ 2022年09月23日 08:08/ 0 赞/ 198 阅读
相关 5 个基本的 REST API 设计指导方针 当我们开始从事API开发的时候,设计问题便出现了. 一个强而有力的API设计方法是API成功的关键要素. 设计糟糕的API会导致API滥用问题,或者更糟:API根本没人使用 ( 怼烎@/ 2022年07月14日 13:14/ 0 赞/ 127 阅读
相关 【设计】RESTful API的十个最佳实践 WebAPI在过去几年里非常的盛行,我们很多以往的技术手段都慢慢的转换为使用WebAPI来开发,因为它的语法简单规范化,以及轻量级等特点,这种方式收到了广泛的推崇。 通 水深无声/ 2022年06月12日 01:37/ 0 赞/ 249 阅读
相关 Rest API 设计 【问题】 在以前的项目经验中,接口请求都是GET或者POST方式;接口定义都是以动词开头,比如,按名称查询某用户信息,都是写成queryByUserName;接口不管对内还是 淡淡的烟草味﹌/ 2022年05月14日 12:53/ 0 赞/ 313 阅读
相关 13 个设计 REST API 的最佳实践 > [原文 RESTful API Design: 13 Best Practices to Make Your Users Happy][RESTful API Design 不念不忘少年蓝@/ 2022年04月03日 08:10/ 0 赞/ 267 阅读
相关 Rest API设计 rest api 设计 分布式应用程序 rest 方式 http协议, 应用更为广泛, 前台应用(app, web)通过 http协议 调用后台服务 刺骨的言语ヽ痛彻心扉/ 2022年03月02日 15:24/ 0 赞/ 257 阅读
相关 RESTful API(二)——RESTful API 设计规范 rest 是一种软件架构风格,如果你们的接口是 rest 接口,那么就可被认为你们的的接口是restful的,英文名词和形容词的区别。 rest 接口是围绕“资源 墨蓝/ 2021年12月14日 07:49/ 0 赞/ 400 阅读
相关 13 个设计 REST API 的最佳实践 1. 了解应用于 REST 之上的 HTTP 知识 如果你想要构建设计优良的 REST API,了解一些关于 HTTP 协议的基础知识是很有帮助的,毕竟磨刀不误砍材工。 清疚/ 2021年09月07日 06:19/ 0 赞/ 369 阅读
还没有评论,来说两句吧...