转载

设计优秀API七大要诀

设计优秀API七大要诀

  英文原文:What makes a good API great?

  一个超棒的 API 必定经过一番精心设计,肯花大量时间、站在用户角度思考问题,这样用户使用起来才会事半功倍。那么,这样的 API 需要具备什么样的条件呢?

  有的放矢

  APIs 不单单是程序的复制品。它是在我们的核心应用不能解决问题时,担当数据分析的角色。

  如果一味追求“做到所有想做的”,那么我们的 APIs 可能会因此变得臃肿而过于复杂。所以好的 API 必须追求用户体验,有切实可行的目标。

  追求极简

  如果一款应用的某个功能一时是A一时是B,那么用户将会给逼疯的。Dropbox 核心 API 在简化这方面就做得不错。其面向的操作对象是单一的,提供了读取 metadata,读取/下载数据共三个操作。开发者可以方便地使用它来进行二次开发,做出功能更丰富的应用。

  简易的说明

  简明扼要的文档能让用户在短时间内掌握相关的使用方法,缩短开发用时,比方说 Github 提供的使用说明。这些将能有助于用户了解不同的使用场合,从而更有信心地创建更复杂的应用。

  支持 OAuth2 协议

  OAuth2.0 是 OAuth 协议的下一版本,更关注客户端开发者的简易性。想象下如果登录程序时,用户不仅需要用户名/密码还得需要安全令牌,那么难道你不想立马换一个程序吗?

  事实上,目前几乎所有的 API 都是这样做的。因此用户不得不花费多余的时间来完成用户认证。认证是需要的,但用户可不这样想。所以不妨参考下 OAuth2 规范对此作出改善。

  多权限设置

  当用户被要求对第三方应用进行权限认证时,考虑最多的一个问题是:这对于我的个人数据有什么影响?

  很多时候,答案是所有权限,这难免会让用户觉得存在风险。GoogleDrive API 做得就不错,它允许开发者对权限进行管理。这样做出的程序会让用户感觉舒服。

  清晰的错误或无误信息反馈

  开发者在使用 API 过程中可能会出现错误,或许是不熟悉,或许是收到了限制;无论是什么,我们建议,以 HTTP 错误代码形式加以说明。

  及时的、清晰的反馈有助于用户明白错误的来龙去脉。HTTP 错误码一般不会引起歧义并含有清晰的错误阐述,所以建议由此入手。

  提供变更检测机制

  APIs 一般是透过 internet 进行访问,如果不对每个调用进行检测,那么很有可能会加重服务器和用户带宽的负担。因此使用合理的变更检测机制(如 ETags)进行检测是很有必要的。

  以上所说的或许看起来比较基础,但是我们应该引起重视;坚持从源头抓起,从小处着手,才能做出最终让用户满意的作品。

正文到此结束
Loading...