怎样设计出优美的Web API

发布时间:2022-01-19 10:45:25 作者:柒染
来源:亿速云 阅读:127

这篇文章主要为大家分析了怎样设计出优美的Web API的相关知识点,内容详细易懂,操作细节合理,具有一定参考价值。如果感兴趣的话,不妨跟着跟随小编一起来看看,下面跟着小编一起深入学习“怎样设计出优美的Web API”的知识吧。

WEB API的应用场景非常丰富,例如:将已有系统的功能或数据开放给合作伙伴或生态圈;对外发布可嵌入到其他网页的微件;构建前后端分离的WEB应用;开发跨不同终端的移动应用;集成公司内部不同系统等等。在上述场景里,你可能是WEB API的使用者,也可能是设计者,但你知道如何评判WEB API的优劣吗?

我们可以从三个维度来评判一个WEB API的优劣:

做到了上述三个方面,我们才有底气将一个WEB API对外开放,接受公众的检验。好的WEB API不仅方便使用,还助于提升个人或企业的技术影响力,从而形成正向循环,带来越来越多的业务价值。为了设计出优美的WEB API,我们需要了解与之相关的设计规范和事实标准,并且在设计开发过程中尽量遵循它们。

URI

反例:http://api.example.com/service/api/users

正例:http://api.example.com/users

反例:http://api.example.com/sv/u

反例:http://api.example.com/Users/12345

反例:http://example.com/API/getUserName

正例:http://api.example.com/v1/items/123456

反例:http://api.example.com/cgi-bin/get_user.php?user=100

反例:获取好友信息,http://api.example.com/friends?id=100

反例:发送消息,http://api.example.com/friend/100/messages

正例:获取好友信息,http://api.example.com/friends/100

正例:发送消息,http://api.example.com/friends/100/messages

脊柱法:http://api.example.com/v1/users/12345/profile-image

蛇形法:http://api.example.com/v1/users/12345/profile_image

驼峰法:http://api.example.com/v1/users/12345/profileImage

查询参数

风格1:http://api.example.com/friends?per-page=50&page=3

风格2:http://api.example.com/friends?limit=50&offset=100

完全符合:http://api.example.com/v1/users?name=ken

全文搜索:http://api.example.com/v1/users?q=ken

模糊搜索:http://yboss.yahooapis.com/ysearch/web?q=ipod

路径元素:http://api.example.com/v1/users/{id}

查询参数:http://api.example.com/v1/users?name=ken

HTTP方法

按照HTTP协议设计的本意,URI用于标识被操作的目标对象(资源),而HTTP方法则是表示操作方法。基于HTTP协议的简单对象访问协议SOAP逐渐被RESTful的原生HTTP协议取代,我们也没有必要画蛇添足,最好就是吃透HTTP协议,充分利用它的特性。

GET /v1/users/123 HTTP/1.1

Host: api.example.com

如果遇到上述HTTP方法无法覆盖的场景,那通常是资源的设计粒度太大了,我们可以把粗粒度的资源分解成多个细粒度的资源。在使用HTTP协议设计WEB API的专业能力上,业界将其划分为四个层级,LEVEL3相对较理想化,缺乏实施的基础,LEVEL2是切实可行的:

响应数据

常用的数据格式有:HTML、XML、JSON、YAML等,如果我们的服务在响应时支持不同类型的数据格式,那应用在调用服务时如何获得期望格式的响应数据呢?通常我们可以考虑采用下述几种指定数据格式的方法:

示例:https://api.example.com/v1/users?format=xml

示例:https://api.example.com/v1/users.json

GET /v1/users

Host: api.example.com

Accept: application/json

响应数据应该包含哪些信息呢?是否越多越好?亦或越少越好,仅仅包含ID?建议是按需返回,根据业务功能所需返回相应的数据。如果一个WEB API需要提供给不同业务场景使用,不同业务场景对数据属性信息的要求不同,或多或少,这种情况我们可以让用户来选择响应的内容,选择方法就是通过查询参数指定:

示例:http://api.example.com/v1/users/123?fields=name,age

响应数据的结构应该尽量扁平化,不要嵌套太深,减少没有具体含义的信息载荷,这样既可以压缩报文尺寸,又可以节省带宽的。当然,如果层级结构更具优势,也可以采用。

出错信息

建议通过HTTP协议首部的状态码来表示出错信息,而不是再封装一层,遵守协议规范的好处是可以减少沟通的成本,也可以利用许多成熟的软硬件产品来处理异常出错信息。HTTP协议定了了五种类型的状态码:

我们需要每种状态码的使用场景,确保正确使用状态码。除此之外,服务还需要向客户端返回详细的出错信息,我们通常可以采用下述两种方法来传递详细的出错信息:

版本管理

随着业务的发展,每个发布上线的WEB API都存在更新修改的可能,那就需要引入版本管理的机制。业界有三种常见的标注WEB API版本的方法:

示例:http://api.linkedin.com/v1/people

示例:http://api.example.com/users/123?v=2

Accept: application/vnd.github.v3+json

Content-Type: application/vnd.github.v3+json 

同样,版本编号也存在业界规范:语义化版本控制(Semantic Versioning)规范,网站地址: semver.org。版本编号由点号连接的3个数字组成,例如:1.2.3,分别表示主版本编号、次版本编号、补丁版本编号,版本编号的增加遵循下述规则:

按照版本编号增长的规则,WEB API的版本编号只需要标注主版本编号就可以了,因为次版本编号、补丁版本编号的增加都可以做到向下兼容,不会影响用户使用,唯有主版本编号增加才需要用户更新升级。除了标注版本信息之外,我们在对外发布WEB API时还需要设计好版本变更的策略,例如:老版本提供多久的过渡期、同时兼容多少个版本、特定版本的终止日期等等。

何为优美?就是符合大众审美的,对于WEB API来说,就是符合标准规范的,这有利于降低用户学习和使用的成本,便于交流,不存在隐没成本。通常,业界存在的标准规范和事实标准都是经过实践筛选出来的,从遵循模仿开始,然后再找机会创新,而不是一上来就重复发明轮子。

WEB API设计领域的标准规范就是URI、HTTP等,我们要最大程度地利用这些协议规范,让每个WEB API都是用户友好(易于使用)、技术友好(支持缓存、易于更改)的。除此之外,我们还需要考虑WEB API的健壮性。

关于“怎样设计出优美的Web API”就介绍到这了,更多相关内容可以搜索亿速云以前的文章,希望能够帮助大家答疑解惑,请多多支持亿速云网站!

相关推荐:web service之api的token设计

免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。

web api

上一篇:mmc.exe进程是什么

下一篇:html5中有哪些常用框架

相关阅读