《Web API设计浅谈系列一》 Web API的概念

本系列共7小节,内容大部分来自《Web API的设计与开发》的读后笔记,也有部分是来自平时的经历。

本系列源自近段时间在开发、设计会员系统API时遇到的问题、学到的设计方法及自己的一点经验感悟,在此做简单记录。

《Web API设计浅谈系列一》 Web API的概念

Web API是指使用HTTP协议通过网络调用的API。

设计原则

  • 易于使用:调用方式简单、文档说明完备;
  • 便于修改:任何API都不可能一成不变,所以这个就显得非常重要;
  • 健壮性好:同函数一样,API也应该具备良好的健壮性;
  • 不怕公开:防止恶意攻击或不当调用,应该具备容错性和安全性;

REST与Web API

REST指的是具象状态传输,是一种设计风格而不是标准。其主要特点包括:

  • 资源有URI指定;
  • 对于资源的操作包括获取、创建、修改和删除资源,刚好对应HTTP协议提供的GET、POST、PUT和DELETE方法

一般的REST是无状态的,有客户端发起请求,基于REST风格设计的API称为RESTful API。

关于RESTful的介绍,参见中文维基百科REST.

在本文中,一般的REST指的是:

  • 符合Fielding的REST风格的Web服务系统
  • 使用符合RPC风格的XML(或JSON)+HTTP接口的系统

其实从某种角度来讲,目前大部分对外公开的Web API基本上都能符合第二条,只是在某些程度上满足或未能满足REST设计风格罢了,笔者认为也不比太多余苛责,实际设计中,只要能易于使用、易于理解即可。

区分API使用对象

  • LSUD:Large Set of Unknown Developers

大部分你未知的开发者,这种情况通常是将API公开到网络向所有开发者提供,使用者的业务场景未知,如很多天气类的API。

这种情况下对于开发者如何使用API的方式你不可能完全考虑到,因此在设计API时就需要做到覆盖到基本操作。如笔者提供会员储值并推送微信消息功能时,提供了一个储值接口和微信消息推送接口,开发者可能只需要调用我方的储值接口而并不需要推送微信消息。

  • SSKD: Small Set of Knows Developers

小部分你所知的开发者,这种情况下常见的是跟公司内部的开发人员对接,你清楚的知道你API的使用者和使用场景。

这时需要根据项目具体业务进行设计,还是以会员储值并推送微信消息为例,此时笔者提供的储值接口就包含推送微信消息的功能,因为推送会员储值微信提醒功能是我们系统的基础功能之一,这样免去了客户端在储值成功后调用推送消息的步骤,减少客户端与服务器的API调用次数。

标签: web api, rest, json, http协议

添加新评论