RESTfulAPI设计标准规范.docxVIP

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