专栏首页CSDN技术头条REST API URI的七大设计原则

REST API URI的七大设计原则

在了解REST API URI设计的规则之前,让我们快速浏览一些我们将要讨论的术语。

URIs

REST API使用统一资源标识符(URI)来寻址资源。在当今互联网上,充斥着各种各样的URI设计规则,既有像//api.example.com/louvre/leonardo-da-vinci/mona-lisa这样能够清楚的传达API资源模型的文章,也有很难理解的文章,例如://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66 ;Tim Berners-Lee在他的“Axioms of Web Architecture”一文中将URI的不透明度总结成一句话:

唯一可以使用标识符的是引用对象。在不取消引用时,就不应该查看URI字符串的内容以获取其他信息。 ——蒂姆·伯纳斯 - 李

客户端必须遵循Web的链接范例,将URI视为不透明标识符。

REST API设计人员应该在考虑将REST API资源模型传达给潜在的客户端开发者的前提下,创造URI。在这篇文章中,我将尝试为REST API URI 引入一套设计规则。

先跳过规则,URI的通用语法也适用与本文中的URI。RFC 3986定义了通用URI语法,如下所示:

URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]

规则1:URI结尾不应包含(/)

这是作为URI路径中处理中最重要的规则之一,正斜杠(/)不会增加语义值,且可能导致混淆。REST API不允许一个尾部的斜杠,不应该将它们包含在提供给客户端的链接的结尾处。

许多Web组件和框架将平等对待以下两个URI:

http://api.canvas.com/shapes/ http://api.canvas.com/shapes

但是,实际上URI中的每个字符都会计入资源的唯一身份的识别中。

两个不同的URI映射到两个不同的资源。如果URI不同,那么资源也是如此,反之亦然。因此,REST API必须生成和传递精确的URI,不能容忍任何的客户端尝试不精确的资源定位。

有些API碰到这种情况,可能设计为让客户端重定向到相应没有尾斜杠的URI(也有可能会返回301 - 用来资源重定向)。

规则2:正斜杠分隔符(/)必须用来指示层级关系

URI的路径中的正斜杠(/)字符用于指示资源之间的层次关系。

例如: http://api.canvas.com/shapes/polygons/quadrilaterals/squares

规则3:应使用连字符( - )来提高URI的可读性

为了使您的URI容易让人们理解,请使用连字符( - )字符来提高长路径中名称的可读性。在路径中,应该使用连字符代空格连接两个单词 。

例如: http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

规则4:不得在URI中使用下划线(_)

一些文本查看器为了区分强调URI,常常会在URI下加上下划线。这样下划线(_)字符可能被文本查看器中默认的下划线部分地遮蔽或完全隐藏。

为避免这种混淆,请使用连字符( - )而不是下划线

规则5:URI路径中首选小写字母

方便时,URI路径中首选小写字母,因为大写字母有时会导致一些问题。RFC 3986将URI定义为区分大小写,但scheme 和 host components除外。

例如:

http://api.example.com/my-folder/my-doc

HTTP://API.EXAMPLE.COM/my-folder/my-doc

这个URI很好。URI格式规范(RFC 3986)认为该URI与URI#1相同。

http://api.example.com/My-Folder/my-doc

而这个URI与URI 1和2不同,这可能会导致不必要的混淆。

规则6:文件扩展名不应包含在URI中

在Web上,(.)字符通常用于分隔URI的文件名和扩展名。

REST API不应在URI中包含人造文件扩展名,来指示邮件实体的格式。相反,他们应该依赖通过Content-Type中的header传递media type,来确定如何处理正文的内容。

http://api.college.com/students/3248234/courses/2005/fall.json http://api.college.com/students/3248234/courses/2005/fall

如上所示:不应使用文件扩展名来表示格式。

应鼓励REST API客户端使用HTTP提供的格式选择机制Accept request header。

为了是链接和调试更简单,REST API应该支持通过查询参数来支持媒体类型的选择。

规则7:端点名称是单数还是复数?

keep-it-simple的原则在这里同样适用。虽然一些”语法学家”会告诉你使用复数来描述资源的单个实例是错误的,但实际上为了保持URI格式的一致性建议使用复数形式。

本着API提供商更容易实施和API使用者更容易操作的原则,可以不必纠结一些奇怪的复数(person/people,goose/geese)。

但是应该怎么处理层级关系呢?如果一个关系只能存在于另一个资源中,RESTful原则就会提供有用的指导。我们来看一下这个例子。学生有一些课程。这些课程在逻辑上映射到学生终端,如下所示:

http://api.college.com/students/3248234/courses——检索id为3248234的学生学习的所有课程的清单。

http://api.college.com/students/3248234/courses/physics——检索该学生的物理课程。

结论

当你在设计REST API服务时,您必须注意这些由URI定义的资源。

正在构建的服务中的每个资源将至少有一个URI标识它。这个URI最好是有意义的,且能充分描述资源。URI应遵循可预测的层次结构,用来提高其可理解性,可用性:可预测的意义在于它们是一致的,它的层次结构在数据关系上是有意义的。

RESTful API是为使用者编写的。URI的名称和结构应该能够向使用者传达更清晰的含义。通过遵循上述规则,您将创建一个更清晰的的REST API与更友好的客户端。这些并不是REST的规则或约束,仅仅是API的增强和补充。

我也建议你来看看http://blog.restcase.com/5-basic-rest-api-design-guidelines/这篇文章。

最后,望大家牢记:你在为你的客户端设计API URI,而不仅仅是为你的数据。

本文分享自微信公众号 - CSDN技术头条(CSDN_Tech)

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2017-06-27

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • OpenStack中的RESTful API是如何实现的?

    OpenStack作为一个开源的IaaS平台,各个组件和服务之间的消息传递都是通过RESTfulAPI和RPC传递,这里主要讲讲它是如何实现REST的。由于大家...

    Python中文社区
  • Python科学计算与数据分析库/包大全

    astropy - A community Python library for Astronomy. 一个面向天文学的Python社区库 ? bcbio-...

    Python中文社区
  • 常用的user32API说明

    整理了一下常用的user32API说明  还有软件Microsoft Spy++供大家下载  Spyv10.00.30319.rar using System;...

    lpxxn
  • 源码阅读再来一发:解读RGW中request的处理流程

    请求处理流程图 ? 以civetweb为例 1. rgw_main.cc为整个radosgw服务的入口,main()函数中根据在ceph.conf的rgw...

    用户1260683
  • Unity Application Block 3月12 发布的版本

    3月12日,Unity 又发布了正式发布之前的版本,这个版本提供了安装程序.并且提供了一个依赖注入在实现方式:Setter injection 的配置API。之...

    张善友
  • 基于DataFrame的StopWordsRemover处理

    stopwords简单来说是指在一种语言中广泛使用的词。在各种需要处理文本的地方,我们对这些停止词做出一些特殊处理,以方便我们更关注在更重要的一些词上。 对于不...

    Spark学习技巧
  • ceph-rest-api 用例

    1.版本问题 0.67-10.x版本如果需要集成现有业务可以考虑这个内置的rest接口,从12.x开始这个接口将被内置的mgr模块替代,后期可能会被移除,所以...

    用户1260683
  • 源码解读bucket 删除中的一些细节

    问题描述 社区群里有人说删除bucket以后还有部分数据残留,用的ceph 10.2.x版本做的验证 测试用例 from boto.s3.connection ...

    用户1260683
  • synchronized与Lock 擂台之战

    面试官:说说synchronized和Lock(或ReentrantLock)的区别 Java 1.5之后,对共享变量访问的协调机制除了之前的synchron...

    用户1260737
  • 探究Python时间处理模块

    不管是哪门语言,碰触时间处理相关议题时,如果开发者要认真面对,往往都会感到异常复杂。 复杂来自两个部份:时间本身就因为历史、经济、政治等考量而复杂,API本身的...

    Python中文社区

扫码关注云+社区

领取腾讯云代金券