RESTfulAPI设计标准规范.docx

背景现在互联网上充斥着大量相关RESTfulAPI（为方便，下文中“RESTfulAPI”简写为“API”）怎样设计文章，然而却没有一个”万能“设计标准：怎样鉴权？API格式怎样？你API是否应该加入版本信息？当你开始写一个app时候，尤其是后端模型部分已经写完时候，你不得不殚精竭虑设计和实现自己apppublicAPI部分。因为一旦公布，对外公布API将会极难改变。在给SupportedFu设计API时候，我试图以实用角度来处理上面提到问题。我期望能够设计出轻易使用，轻易布署，而且足够灵活API，本文所以而生。API设计基础要求网上很多相关API设计见解全部十分”学院派“，它们可能更有理论基础，不过有时却和现实世界脱轨（所以我是自由派）。所以我这篇文章目标是从实践角度出发，给出目前网络应用API设计最好实践（当然，是我认为最好了~），假如认为不适宜，我不会遵从标准。当然作为设计基础，多个必需标准还是要遵守：当标准合理时候遵守标准。API应该对程序员友好，而且在浏览器地址栏轻易输入。API应该简单，直观，轻易使用同时优雅。API应该含有足够灵活性来支持上层ui。API设计权衡上述多个标准。需要强调是：API就是程序员UI，和其它UI一样，你必需仔细考虑它用户体验！使用RESTfulURLs和action.即使前面我说没有一个万能API设计标准。但确实有一个被普遍认可和遵守：RESTfu设计标准。它被RoyFelding提出（在她”基于网络软件架构“论文中第五章）。而REST关键标准是将你API拆分为逻辑上资源。这些资源经过http被操作（GET,POST,PUT,DELETE）。那么我应该怎样拆分出这些资源呢？显然从API用户角度来看，”资源“应该是个名词。即使你内部数据模型和资源已经有了很好对应，API设计时候你仍然不需要把它们一对一全部暴露出来。这里关键是隐藏内部资源，暴露必需外部资源。在SupportFu里，资源是ticket、user、group。一旦定义好了要暴露资源，你能够定义资源上许可操作，和这些操作和你API对应关系：GET/tickets#获取ticket列表GET/tickets/12#查看某个具体ticketPOST/tickets#新建一个ticketPUT/tickets/12#更新ticket12.DELETE/tickets/12#删除ticekt12能够看出使用REST好处于于能够充足利用http强大实现对资源CURD功效。而这里你只需要一个endpoint：/tickets,再没有其它什么命名规则和url规则了，cool！这个endpoint单数复数一个能够遵从规则是：即使看起来使用复数来描述某一个资源实例看起来别扭，不过统一全部endpoint，使用复数使得你URL愈加规整。这让API使用者愈加轻易了解，对开发者来说也更轻易实现。怎样处理关联？相关怎样处理资源之间管理REST标准也有相关描述：GET/tickets/12/messages-Retrieveslistofmessagesforticket#12GET/tickets/12/messages/5-Retrievesmessage#5forticket#12POST/tickets/12/messages-Createsanewmessageinticket#12PUT/tickets/12/messages/5-Updatesmessage#5forticket#12PATCH/tickets/12/messages/5-Partiallyupdatesmessage#5forticket#12DELETE/tickets/12/messages/5-Deletesmessage#5forticket#12其中，假如这种关联和资源独立，那么我们能够在资源输出表示中保留对应资源endpoint。然后API使用者就能够经过点击链接找到相关资源。假如关联和资源联络紧密。资源输出表示就应该直接保留对应资源信息。（比如这里假如message资源是独立存在，那么上面GET/tickets/12/messages就会返回对应message链接；相反假如message不独立存在，她和ticket依附存在，则上面API调用返回直接返回message信息）不符合CURD操作对这个令人迷惑问题，下面是部分处理方法：重构你行为action。当你行为不需要参数时候，你能够把active对应到activated这个资源，（更新使用patch）.以子资源对待。比如:github上，对一个gists加星操作：PUT/gists/:id/star而且取消星操作：DELETE/gists/:id/star.有时候action实在没有难以和某个资源对应上比如sear