关于API:好的设计和坏的设计【eolink翻译】
以前开发或更新 API 时,我们经常需要深入讨论对 API 的结构、命名和功能等,这个花费了大量的时间。
随着 API 行业的蓬勃发展,API 设计也越来越重要。这么多年发展下来,一些如REST API之类的规则也受到大多数人认可,这些规则可以应用于开发流程中,帮助团队快速达成共识,达到提效的目的。
接下来会介绍 API 设计的原理和规则。而在本文中,我们将专注于 Web API。
先用一句话来解释一下,API 是 Application(应用程序)、Programming(编程)和 Interface(接口)的缩写组合,顾名思义,通过一个编写好的接口,连接两个应用程序,可以内部使用,也可以对外开放。
基本上,每次我们使用 Web 应用程序、发送消息或访问某个 URL 时,都在使用对应的 API ,无论它是客户端应用程序还是服务器应用程序,都是通过 API 来传递数据。
由于 API 和其他一切之间的所有通信都是通过 HTTP 完成的,因此 HTTP 非常重要,需要根据不同的目的和需求,采用不同的请求方法:
GET — 请求指定资源的表示。使用 GET 的请求应该只检索数据。
POST — 向指定资源提交数据。
PUT — 用请求数据替换目标资源的所有当前表示。
DELETE — 删除指定的资源。
PATCH — 对资源应用部分修改。
具体的用法可以在公众号其他文章中了解,网上也有很多相关的内容,就不过多展开。
开发技术在不断发展,API 架构和协议也越来越多。不同的架构和协议,在制定数据类型、命令方式、功能上都有所不同。以前最流行的是基于 XML 的协议,现在也逐渐被 JSON 取代。
而当今世界上最常见的 API 架构毫无疑问是 REST 。当我们使用 REST API 时,必须遵循 JSON 的规范,以有效的 JSON 格式发出测试请求。好的 API 通常会遵循这些规则:
API 必须与后端、数据存储、客户端等分开。考虑到安全性和灵活性,API 必须是单独的层级;
不同的请求应该互不干扰,独立处理。这也意味着每个请求都需要包含处理它所需的所有信息;
API 应该独立于客户端外发送请求,以相同的方式工作。例如在 Web 服务器、负载平衡器还是任何其他客户端;
资源应该在客户端或服务器端应该是可缓存的。这可以提高客户端的性能,同时提高服务器端的可拓展性;
处理错误并返回相应的错误代码。帮助用户了解是404还是其他问题;
API 必须是有容错的。用户有时因为物理原因如网络超时等,发出了重复的请求,这样的请求应该返回相同的结果;
使用 Eolink 或其他工具生成规范的 API 文档。不管是使用还是工作交接,都需要用到 API 文档。
命名端点也有一些很好的方式:
只使用名词:端点应该用指定资源内容的名词命名,而不是为正在执行的功能添加动词。例如命名端点 /users 并使用不同的 HTTP 方法来处理用户实体,而不是创建多个 /get-user 、/add-user 等端点;
使用清晰的名称:端点的名称应该清晰直观。不要使用任何快捷方式或缩写,除非很明显 - /ids 是可以理解的并且比 /identification-numbers 更可取;
通过正斜杠构建层次结构:将端点分组为逻辑组。如 /departments/ids 和 /departments/managers ,比 /departments-ids 和 /departments-managers 更好;
仅使用小写:URL 是区分大小写的,因此最好尽量避免使用大写;
使用“-”分隔单词:端点名称中的不同单词通常用“-”分隔,而不是下划线或骆驼拼写法;
避免使用特殊字符:URL 只能使用 ASCII 字符集发送和接收,因此可以只使用该字符集中的字符。同时其他如“%”,“[]”,“{} ”,“|”,“,”“<>” 最好也尽量避免使用。
大多数 REST API 是与微服务架构一起制作的。
在这种情况下,这种 API 结构将提供更改底层逻辑、添加或删除组件等的灵活性,而无需更改与其他服务的其他通信协议。
相信你也对 Web API 的设计有了一定的了解了,这是无数人验证过的合理的优秀的方案,尝试一下应用到工作中吧!
图中所使用的的接口管理工具是eolink,感兴趣可以自行使用:www.eolink.com
关于API:好的设计和坏的设计【eolink翻译】的更多相关文章
- 如何优化API?8个实用技巧!【eolink翻译】
使用 API 可以让公司利用现代连接的力量来帮助他们扩大全球影响力.传输数据和改进集成.由于 API 使企业能够简化流程并增强可用性,所以企业会使用一些优化策略,不断优化流程,比如接下来要说到的8个技 ...
- atitit.eclipse有多少api 扩展点,以及扩展点的设计
atitit.eclipse有多少api 扩展点,以及扩展点的设计 不赞成使用的.作废的以及内部的扩展点 [扩展]页显示了几个你不应该在你的插件中使用的扩展点.在附表C.1的[描述]栏中,我们使用如 ...
- 2014年的Google I/O app设计中的材料设计-渣渣的翻译
又是一篇翻译,用了三个多小时.http://android-developers.blogspot.co.id/2014/08/material-design-in-2014-google-io-ap ...
- paip.自适应网页设计 跟 响应式 设计方法与工具补充(2)o54
paip.自适应网页设计 跟 响应式 设计方法与工具补充(2)o54 #-----响应式 设计框架 Bootstrap比较热门. Foundation 号称是世界上最先进的响应式前端框架. #---绝 ...
- paip.自适应网页设计 跟 响应式 设计的区别跟原理and实践总结
paip.自适应网页设计 跟 响应式 设计的区别跟原理and实践总结 响应式Web设计(Responsive Web design)的理念是: 1 #-----------自适应布局VS响应式布局 2 ...
- 经典信息图表:2013 扁平设计 VS 拟物设计
inTacto 是一家互动数字公司,由 Alejandro Lazos 和 Sebastian Caramés 成立于2001年.他们刚刚发布一个信息图表:<平面设计 VS 现实主义>.这 ...
- paip.自适应网页设计 同 响应 与设计的原理的差and实践总结
paip.自适应网页设计 同 响应 与设计的原理的差and实践总结 响应式Web设计(Responsive Web design)的理念是: 1 #-----------自适应布局VS响应式布局 2 ...
- PPT资料下载 - 问题驱动的软件测试设计:强化测试用例设计
测试用例设计是整个软件测试过程中非常重要的测试活动,需求规格说明是测试人员开展测试设计的主要参考输入.而在测试实践中基于需求规格说明得到的测试用例,在测试覆盖率.测试效率.测试有效性和测试质量等方面的 ...
- 《认知与设计:理解UI设计准则》【PDF】下载
<认知与设计:理解UI设计准则>[PDF]下载链接: https://u253469.pipipan.com/fs/253469-230382276 内容介绍 <图灵交互设计丛书·认 ...
随机推荐
- mask-image实现聚光灯效果
大家好,我是半夏,一个刚刚开始写文的沙雕程序员.如果喜欢我的文章,可以关注 点赞 加我微信:frontendpicker,一起学习交流前端,成为更优秀的工程师-关注公众号:搞前端的半夏,了解更多前端知 ...
- Hadoop(二)Hdfs基本操作
HDFS HDFS由大量服务器组成存储集群,将数据进行分片与副本,实现高容错. 而分片最小的单位就是块.默认块的大小是64M. HDFS Cli操作 官网https://hadoop.apache.o ...
- [题解][P5206][WC2019] 数树 (op = 1)
简要题意 给定 \(n, y\). 一张图有 \(|V| = n\) 个点,现在给出两棵树 \(T_1=G(V, E_1)\) 和 \(T_2=G(V, E_2)\). 定义这两棵树的权值 \(F(E ...
- openstack之Designate组件,入门级安装(快速)
@ 目录 前言 架构 前提准备 创建 DNS 服务 API 端点 安装和配置组件 验证操作 前言 Designate 是一个开源 DNS 即服务实施,是用于运行云的 OpenStack 服务生态系统的 ...
- python爬取豆瓣电影Top250(附完整源代码)
初学爬虫,学习一下三方库的使用以及简单静态网页的分析.就跟着视频写了一个爬取豆瓣Top250排行榜的爬虫. 网页分析 我个人感觉写爬虫最重要的就是分析网页,找到网页的规律,找到自己需要内容所在的地方, ...
- 被迫开始学习Typescript —— class
TS 的 class 看起来和 ES6 的 Class 有点像,基本上差别不大,除了 可以继承(实现)接口.私有成员.只读等之外. 参考:https://typescript.bootcss.com/ ...
- 网络协议之:sctp流控制传输协议
目录 简介 TCP有什么不好 sctp的特点 总结 简介 要讲网络协议,肯定离不开OSI(Open System Interconnection)的七层模型. 我们一般关注的是网络层之上的几层,比如I ...
- c# SendInput模拟输入字符和按键
介绍: 该程序本意是为了在彩六里打中文用的,现整理出来供大家复制粘贴.(源程序已开源至GitHub - 彩六中文输入) 主要使用SendInput函数,与c语言中用法一致.(部分代码来自网络) 命名空 ...
- Spark: 单词计数(Word Count)的MapReduce实现(Java/Python)
1 导引 我们在博客<Hadoop: 单词计数(Word Count)的MapReduce实现 >中学习了如何用Hadoop-MapReduce实现单词计数,现在我们来看如何用Spark来 ...
- 解锁!玩转 HelloGitHub 的新姿势
本文不会涉及太多技术细节和源码,请放心食用 大家好,我是 HelloGitHub 的老荀,好久不见啊! 我在完成 HelloZooKeeper 系列之后,就很少"露面了".但是我对 ...