如何设计优秀的 API

5、优秀 API 设计指南 本文详细介绍了优秀API设计的指南和最佳实践,涵盖URI格式设计、REST服务的路径设计、HTTP动词的正确使用、查询参数和响应代码的处理、错误对象的设计等内容。通过遵循这些原则,可以提升API的可读性、可维护性和扩展性,从而为开发者和用户提供更好的体验。文中还结合了实际案例,帮助读者更好地理解和应用这些设计原则。 阅读详情
API的设计是编程中最困难的事情。甚至有人认为,哪怕你已经有着十年的相关经验,也仅仅只能接触尝试API的设计。我们也曾经或多或少的为了那些缺乏经验的程序员所设计的一些API吃了苦头。然而,如果你能在这个过程中获得了一位优秀的导师对你进行指点,那么你的进步会呈几何速度提升。

本文作者就从他的导师那学会了一套不受框条约束的方法,称之为“90-9-0.9”,可能最难的还是剩下的那0.1。原文内容如下:

幸运的是,在刚刚走出大学校门时,我加入 Atalasoft。这是一间专门设计开发API的公司,也因此我获得了在API方面接受严格培训的机会。我的导师是 Steve Hawley,他是一个喜欢在研究解决各种疑难杂症的问题上花费大量时间的人,并且他会把这些解决方面整理出来。Steve并没有那么多耐心去给新手充当一个保姆,所以他总是喜欢把整理好的方案刻录成光碟交给我们。在这种方式的督促下,我学的很快。

他的人生观、他的思想从来不会被一些框框条条所束缚,对于他的那套哲学我称之为90-9-0.9:

  • 其中90%意味着人们仅需要通过剪切、粘贴API文档中的几行代码就可以解决在一般情况下遇到的问题。
  • 接下来的9%是需要对你的目标进行简单地配置,甚至有些问题在几分钟内就可以简单地通过文档查询或者技术团队的支持来解决。
  • 最后的0.9%,是指我们需要面对会有人用各种方式滥用你开发的库,有的时候是因为本身的性能问题,有的时候却是因为使用者利用了一些难以想象的古怪(但偏偏是可执行的)手段。当然为了保证客户的需求,牺牲这0.9%也是完全可取的。
  • 最后,还有0.1%的人会完全曲解你的产品,这会让我们的感到非常难受。最好通过市场调查去看看是否需要重视这类用户,看看他们的是否值得让自己去扩展库且添加他们。
对于那些难以满足的用户,Atalasoft做的条形码产品就是一个很好的例子,当初在产品上投入了很多精力去仔细进行性能调优和预处理,对许多文档进行扫描后都没有发现问题。预处理完毕后,我们尝试了各种类型的条形码,在最短的时间内给任何可以进行扫描操作的人进行扫描。

使用者可以通过修改一个简单的枚举类型的属性进行配置。但是有些扫描的确很困难,比如扫描一个缠绕在香蕉上的条形码。对这种情况,可能会让你无法扫描甚至于更换整个条形码引擎。但就算如此,也不会有谁拿着这样的产品去扫描一条宠物店的狗身上剃出来的条形码吧。如果你是这样的用户,建议还是去找其它的产品吧。

当我第一次接触到这种情况的时候,我感觉这真的是一个很糟糕的设计。整个组件就像一个完全DIY的插件系统。Atalasoft不会为了一些人的审美观来进行优化,他们只会为了减轻用户对其产品支持的负担而进行不断调优。正如我自己不喜欢把面向对象的思想用来编写内部库一样,单单在开放一个所有级别的用户都能操作的简单接口上,我认为没有比这更好的范式。

在过去的两年里,我一直在Bayard Rock公司负责API方面的工作,我们研发的项目主要用于打击一些洗黑钱活动。这意味着需要做很多小型的实验项目,偶尔一些中型的实验项目也会一并在以后会被整合到业内同行的大型平台上。在大多数情况下,Atalasoft风格的黑匣子是起不了任何作用的。我们只有一个客户并且根据他们的需求对我们的外部API进行调整。

但是,在一个细粒度级别中,代码的重用是非常重要的。在这种情况下,最重要的就是构建一个大型数据库,把许多分类函数快速的组合在一起(通过简单的组合和不全面的单元测试)而后我们让然对我们产品的运作信心十足。到目前为止,我们仍在不断地进行优化实验并且快速发展我们的组件。

那么,什么是好的API设计?就像我们之前所提到了: 不要被框框条条所束缚,设计上要按照常规来进行,同时在理解用户需求的前提下加入我们的设计理念,同时自己的产品在遇到一个会在狗身上剃出条形码并对其扫描的不靠谱用户,你应该果断放弃为他设计产品。
物体检测之非极大值抑制:NMS、softNMS、softerNMS、IoU-Net 当前的物体检测算法为了保证召回率,对于同一个真实物体往往会有多个的候选框输出。由于多余的候选框会影响检测精度,因此需要利用NMS过滤掉重叠的候选框,得到最佳的预测输出。当前有如下几种较为常见的NMS方法, 1.基本NMS 非极大值抑制, 顾名思义就是抑制不是极大值的边框,这里的抑制通常是直接去掉冗余的边框。 这个过程涉及以下两个量化指标: 1.预测得分:NMS假设一个边框的预测得分越高,这个框... 阅读详情

相关推荐

Reality Capture控制点修复/合并模型

通过增加控制点/修改对齐设置参数来修复模型被分为两个部分的解决方法

草履虫建模的博客 5259

通用API数据结构及错误码设计规范

一、前言 1、设计“标准错误信息结构”的背景和意义 考虑到如下几个方面: 1)便于使用方(大众用户)知道错误的原因 2)便于使用方(程序 或 程序员)知道错误的原因 3)便于知道错误的原因,以及可能的排查和恢复措施 4)知道错误的类型,便于对其进行监控(分类和统计)或者 触发特定动作 设计策略:首先考虑2)3)4)。 针对于 面向 程序处理 或者 程序员使用的数据,跟 面向于 普通大众用户的数据,其错误码(code)和错误信息(msg)的设计可能是有...

zollty的专栏 4071

TwinCAT3与Matlab Simulink集成开发:如何快速生成和调试TcCOM模块

本文详细介绍了如何将TwinCAT3与Matlab Simulink进行深度集成,实现从控制算法模型到实时TcCOM模块的高效开发。通过环境搭建、模型配置、代码生成、系统集成与调试的完整流程,工程师可以快速将Simulink算法部署到倍福实时控制平台,大幅缩短开发周期并提升可靠性。

ik67890123的博客 225

api设计干货

现在流行云端化,前后端分离。要实现这样的设计就必须开发接口。接口开发就好比一个产品换了包装。业务逻辑上是没有任何变化的,唯一变化的就是数据接收和返回做了新的处理。接口开发需要注意以下几个基本点。确定接口风格到底你是采用传统的风格,还是使用restful风格。这很重要,直接关系到你的接口长相,换句话说,让对接你的人考到你的接口是什么样的。 比如微信的接口,采用的是传统的风格,url中带上token,

shooke笔记 437

AGX Orin设计-外围电路设计之一

AGX ORIN是英伟达Jetson系列中算力规格最高端的模组,其高达200TOPS/275TOPS的算力可以为各类场景提供澎湃的算力支持,本篇文章针对AGX ORIN的常规外围电路设计做分析描述。

zhiyuchenkeji的博客 4491

2021-08-20

通过QQ号获取绑定的手机号 导语 偶有奇想,我们可以通过手机号来搜索获取其对应的QQ号,那么,反过来呢? 一.缩小范围 由于手机号属于隐私数据,腾讯QQ并没有直接给出通过QQ号查找对应手机号的接口。 国内的手机号有十一位数字,从数学的角度上来说,包含了1011种可能。如果遍历这1011个数据,通过QQ中手机号查找QQ号的接口来寻找,未免太过费时费力,根据网上查到的资料,同一个QQ号,在十分钟内只能进行30次查询(未验证)。因此,直接遍历的方法不现实。 在这10^13个数据中,包含着大量的可去除的无用数据。我

m0_56063822的博客 4742

api 状态码设计

一、状态码的作用 设计状态码的主要目的是帮助我们提高沟通效率,降低代码的维护成本。 二、参数约定 1、虽说是返回码设计,但是只有code是不行的,还要有对应的message,让人可以看懂 字段 类型 说明 code int 返回码 message string 返回码说明 2、除了有code和message还需要对code进行分段通过分段可以迅速定位到问题 返回码值 说明 99999 系统发生未知异常 0 成功 10000-19999 参数校验错误 200

分享Android开发知识 671

WRFDA如何读取风云四号A 星的GIIRS数据?

🏆本文收录于 《全栈 Bug 调优(实战版)》 专栏。专栏聚焦真实项目中的各类疑难 Bug,从成因剖析 → 排查路径 → 解决方案 → 预防优化全链路拆解,形成一套可复用、可沉淀的实战知识体系。无论你是初入职场的开发者,还是负责复杂项目的资深工程师,都可以在这里构建一套属于自己的「问题诊断与性能调优」方法论,助你稳步进阶、放大技术价值。

**My Coding Family** 1031

后端Coder如何做好代码设计?

点击上方IT牧场,选择置顶或者星标技术干货每日送达本文来源:http://r6d.cn/BEUZ说明:生鲜电商属于一个软件的产品,那么如何做好代码设计呢?代码设计,是程序员做项目时...

ITMuch的专栏 331

基于OpenClaw的自动化文件管理与文档分类系统设计与实现

本文介绍了一种基于OpenClaw的自动化文件管理与文档分类系统。系统采用三层架构设计,包含数据层、逻辑层和应用层,核心组件涵盖文件扫描、处理、分类、移动等功能。技术选型上使用Python/FastAPI作为后端,结合PostgreSQL/Elasticsearch/MinIO存储方案,并整合scikit-learn/PyTorch等AI技术实现智能分类。系统实现了文件递归扫描、增量扫描、元数据提取等功能,通过文件哈希和修改时间检测变化。该方案能有效提升文件管理效率,实现文档的自动化分类与智能管理。

一键难忘的博客 758

流体仿真软件:COMSOL Multiphysics二次开发_(3).流体仿真基础理论

流体仿真基础理论包括流体的基本性质、流体运动方程、边界条件、初始条件、湍流模型和网格生成等。在使用COMSOL Multiphysics进行流体仿真时,正确设置这些参数和条件是获得准确仿真结果的关键。通过实际应用案例,可以更好地理解如何在COMSOL中进行流体仿真,并提取和分析仿真结果。希望本文对流体仿真初学者和从业人员有所帮助。

kkchenjj的博客 1343

API的HTTP状态码设计

一、现状:前天与后端开发人员讨论了API接口的设计。有以下三种方案: 1、原始HTTTP协议 HTTP状态码就是该Request的状态码,不应该与后端业务混在一起(这也是一部分人使用该方案的理由)。比如200表示该Request成功了,具体业务有没有操作成功还需要在response body里再标记,比如1表示操作成功,0表示操作失败。 2、HTTP协议 RESTful 风格 充分利用HTTP状

天盟 - 技术博客 - Eamon 6735

智能车浅谈——手把手让车跑起来(电磁篇)

手把手让你的电磁车上路。

qq_41954556的博客 7万+

优秀的API接口设计原则及方法

到目前为止,已经负责API接近两年了,这两年中发现现有的API存在的问题越来越多,但很多API一旦发布后就不再能修改了,即时升级和维护是必须的。一旦API发生变化,就可能对相关的调用者带来巨大的代价,用户需要排查所有调用的代码,需要调整所有与之相关的部分,这些工作对他们来说都是额外的。如果辛辛苦苦完成这些以后,还发现了相关的bug,那对用户的打击就更大。如果API经常发生变化,用户就会失去对提供方

资深男人 1万+

RU DOS版、EFI版32bit/64bit BIOS常用工具

DOS版、EFI版的RU工具,可用来查看IO、MEM、PCI、SMBIOS等资源。亲测在EFI SHELL下可用。

Devexpress16.2.6破解工具

Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具

如何设计优秀的API(1)

  原文:How to design a good API翻译时间:31-08-2007译者:周林( 欢迎转载,转载请注明出处^_^) 摘要:    本文以NetBeans架构下API的设计为背景,描述了如何设计优秀的API(Application Programming Interface)。   目录:1. 为何要有API?2. 什么是A

Cubie's Blog(カゼドウのブログ) 1065

假人有限元模型

假人模型,车辆碰撞假人有限元模型,适合做乘员安全的研究者利用

优秀API设计的十大原则

每个软件开发人员都使用API。“优秀”的API设计就像魔法。不过,我不知道有多少人可以解释为什么有的API很复杂、很难学,而有的则干净、简单、使用起来堪称是一种快乐。关于这个问题,我将在文中回答,并提供优秀API设计的十条法则。 1.只做你今天需要的 这是最顶级的规则。只解决今天必须解决的问题,最小化需要完成的答案。解决明天的问题的诱惑力是巨大的。但是一定要顶住诱惑!不要提前发

webxscan.com 364

怀旧版电脑GBC模拟器

再现原版GBC掌机的界面,电脑运行连游戏界面都一样大小,很怀旧,很真实,(英文版)强烈推荐,很小的文件,很难才找到的。

如何设计一款优秀的API

设计看似简单,其实里面的学问还不少,在整个设计流程中,一不小心就会陷入各种陷阱之中,给你带来后患无穷的危害。Joshua Bloch是Google的首席Java架构师,他在一篇PPT里向大家讲述了如何设计一款优秀的API。     【编者按】随着近来软件规模的日益庞大,API编程接口的设计变的越来越重要。良好的接口设计可以降低系统各部分之间的相互依赖,提高组成单元的内聚性,降低组成单元间的耦合度

u013703167的专栏 373

设计优秀API的十大原则

每个软件开发人员都使用API。“优秀”的API设计就像魔法。不过,我不知道有多少人可以解释为什么有的API很复杂、很难学,而有的则干净、简单、使用起来堪称是一种快乐。关于这个问题,我将在文中回答,并提供优秀API设计的十条法则。 1.只做你今天需要的 这是最顶级的规则。只解决今天必须解决的问题,最小化需要完成的答案。解决明天的问题的诱惑力...

weixin_34315189的博客 2414

逐步改善,设计优秀API

逐步改善,设计优秀API

重剑无锋,大巧不工。。。 1126

设计优秀API的五大规则

设计优秀API的五大规则   摘要:如何设计一款优秀的API已成为许多程序员的奋斗目标,而本文着重介绍了如何设计优秀的Java API,作者提炼了几条规则:建立强有力的条款;在组合上运用对称;使用重载;参数顺序一致等。 人们在如何设计一款优秀的API上有着很强烈的意识。在互联网上有关API方面的网页和书籍有很多很多。本文我们将重点关注设计优秀API的规则。 规则就是当发

paullmq的专栏 697

优秀的 API 接口设计规范

任何api,从权限上,可归结为匿名api和非匿名api,前者不需要验证,后者需要验证。

TOOZOOY的博客 1244

如何设计出优秀的Restful API?

如何设计出优秀的Restful API? 转载于:https://www.cnblogs.com/linjiqin/p/9557292.html

weixin_30300523的博客 65
上一篇: 找不到女友以工作忙为由则是能力低
下一篇: API设计的一些心得总结
代码兔
博客等级 码龄16年 21粉丝 23原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值