restful api 设计最佳实践 -

restful api 设计最佳实践 -

ID:14190457

大小:104.50 KB

页数:11页

时间:2018-07-26

restful api 设计最佳实践 -_第1页
restful api 设计最佳实践 -_第2页
restful api 设计最佳实践 -_第3页
restful api 设计最佳实践 -_第4页
restful api 设计最佳实践 -_第5页
资源描述:

《restful api 设计最佳实践 -》由会员上传分享,免费在线阅读,更多相关内容在行业资料-天天文库

1、摘要:目前互联网上充斥着大量的关于RESTfulAPI(为了方便,以后API和RESTfulAPI一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API是否应该加入版本信息?背景目前互联网上充斥着大量的关于RESTfulAPI(为了方便,以后API和RESTfulAPI一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API是否应该加入版本信息?当你开始写一个app的时候,特别是后端模型部分已经写完的时候,你不得不殚精竭虑的设计和实现自己app的publicAPI部分。因

2、为一旦发布,对外发布的API将会很难改变。在给SupportedFu设计API的时候,我试图以实用的角度来解决上面提到的问题。我希望可以设计出容易使用,容易部署,并且足够灵活的API,本文因此而生。API设计的基本要求网上的很多关于API设计的观点都十分”学院派“,它们也许更有理论基础,但是有时却和现实世界脱轨(因此我是自由派)。所以我这篇文章的目标是从实践的角度出发,给出当前网络应用的API设计最佳实践(当然,是我认为的最佳了~),如果觉得不合适,我不会遵从标准。当然作为设计的基础,几个必须的原则还是要遵守的:1.当标准合理的时候遵守标准。2.API

3、应该对程序员友好,并且在浏览器地址栏容易输入。3.API应该简单,直观,容易使用的同时优雅。4.API应该具有足够的灵活性来支持上层ui。5.API设计权衡上述几个原则。需要强调的是:API的就是程序员的UI,和其他UI一样,你必须仔细考虑它的用户体验!使用RESTfulURLs和action.虽然前面我说没有一个万能的API设计标准。但确实有一个被普遍承认和遵守:RESTfu设计原则。它被RoyFelding提出(在他的”基于网络的软件架构“论文中第五章)。而REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作(GET,PO

4、ST,PUT,DELETE)。那么我应该如何拆分出这些资源呢?显然从API用户的角度来看,”资源“应该是个名词。即使你的内部数据模型和资源已经有了很好的对应,API设计的时候你仍然不需要把它们一对一的都暴露出来。这里的关键是隐藏内部资源,暴露必需的外部资源。在SupportFu里,资源是ticket、user、group。一旦定义好了要暴露的资源,你可以定义资源上允许的操作,以及这些操作和你的API的对应关系:·GET/tickets#获取ticket列表·GET/tickets/12#查看某个具体的ticket·POST/tickets#新建一个ti

5、cket·PUT/tickets/12#更新ticket12.·DELETE/tickets/12#删除ticekt12可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里你只需要一个endpoint:/tickets,再没有其他什么命名规则和url规则了,cool!这个endpoint的单数复数一个可以遵从的规则是:虽然看起来使用复数来描述某一个资源实例看起来别扭,但是统一所有的endpoint,使用复数使得你的URL更加规整。这让API使用者更加容易理解,对开发者来说也更容易实现。如何处理关联?关于如何处理资源之

6、间的管理REST原则也有相关的描述:·GET/tickets/12/messages-Retrieveslistofmessagesforticket#12·GET/tickets/12/messages/5-Retrievesmessage#5forticket#12·POST/tickets/12/messages-Createsanewmessageinticket#12·PUT/tickets/12/messages/5-Updatesmessage#5forticket#12·PATCH/tickets/12/messages/5-Parti

7、allyupdatesmessage#5forticket#12·DELETE/tickets/12/messages/5-Deletesmessage#5forticket#12其中,如果这种关联和资源独立,那么我们可以在资源的输出表示中保存相应资源的endpoint。然后API的使用者就可以通过点击链接找到相关的资源。如果关联和资源联系紧密。资源的输出表示就应该直接保存相应资源信息。(例如这里如果message资源是独立存在的,那么上面GET/tickets/12/messages就会返回相应message的链接;相反的如果message不独立存在

8、,他和ticket依附存在,则上面的API调用返回直接返回message信息)不符合CURD的

当前文档最多预览五页,下载文档查看全文

此文档下载收益归作者所有

当前文档最多预览五页,下载文档查看全文
温馨提示:
1. 部分包含数学公式或PPT动画的文件,查看预览时可能会显示错乱或异常,文件下载后无此问题,请放心下载。
2. 本文档由用户上传,版权归属用户,天天文库负责整理代发布。如果您对本文档版权有争议请及时联系客服。
3. 下载前请仔细阅读文档内容,确认文档内容符合您的需求后进行下载,若出现内容与标题不符可向本站投诉处理。
4. 下载文档时可能由于网络波动等原因无法下载或下载错误,付费完成后未能成功下载的用户请联系客服处理。