首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >[翻译]RESTful API设计系列三:URLs

[翻译]RESTful API设计系列三:URLs

作者头像
陆道峰
发布2020-06-17 22:04:42
7550
发布2020-06-17 22:04:42
举报

说明

  • 原文链接:http://restful-api-design.readthedocs.io/en/latest/urls.html
  • 用时: 2h

Entry Point

RESTful API有且只有一个入口点(entry point)。入口点的URL要告知API客户端,以便它们可以找到。

技术上讲,入口点可以被看作任何集合外的单个资源。通常入口点包含下列部分或全部信息:

  • API版本信息,支持的特性等。
  • 顶层集合列表。
  • 单个资源列表。
  • API设计者认为有用的信息,比如:操作状态的简短描述、统计信息等。

URL结构

API中的每个集合和资源都有自己的URL。URLs不能通过客户端来构造。客户端只能使用API生成的链接。

推荐的URL规范是在API入口点后添加可用的集合或者资源的路径。这最好通过例子来描述。下图表格来自Rails中的“路由”实现,使用“:name”URL变量风格。

URL

Description

/api

The API entry point

/api/:coll

A top-level collection named “coll”

/api/:coll/:id

The resource “id” inside collection “coll”

/api/:coll/:id/:subcoll

Sub-collection “subcoll” under resource “id”

/api/:coll/:id/:subcoll/:subid

The resource “subid” inside “subcoll”

尽管子集合可能有任意层嵌套,以我个人经验,如果可以的话最好把嵌套深度限制在2以内。URLs越长,越难使用简单的命令行工具比如curl。

Relative vs Absolute

强烈建议API生成绝对地址的URLs。

理由主要是方便客户端,这样客户端就不要去匹配相对URL对应资源的绝对URL了。毕竟URL RPF中指定的检测基本URL的算法就已经非常复杂了。查找基本URL的方法之一是解析请求资源的URL。由于一个资源可能出现在多个URLs中(比如,资源作为集合的一部分出现在URL,或者单个资源),这样客户端记住每个URL是很大的开销。通过使用绝对URL就避免了这个问题。

URL模板

已经有关于URL模板的草案了。当目标URL中存在查询参数时,URL模板会很有帮助。即便如此我还是推荐保守(conservative)使用模板。目前为止URL模板唯一的使用案例是在集合中搜索。搜索条件可以作为GET风格的查询参数附加到集合URL后面。

我建议使用URL模板规范的”字面扩展“(literal expansion)部分,因为我认为规范的”表达式扩展“部分非常复杂,几乎没有优势。

变量

有时你的工作需要处理资源中的变量部分。以我们的RHEV-M API为例,当虚拟机运行时需要更新虚拟机里面的一些属性。这相当于资源的热插拔(This amounts to a hot plug/unplug of the resource),这与改变已经保存的表示是完全不同的操作。好的实现方法是在URL中使用”;variant”,比如:

URL

Description

/api/:coll/:id;saved

Identifies the saved variant of a resource.

/api/:coll/:id;current

Identifies the current variant of a resource.

RFC3986允许使用分号来提供特定于路径段的选项。使用”?variant”格式查询参数的优势是,该格式只能用于路径段。

译者说

本文作者介绍了API的入口点(entry point),推荐使用RESTful API的绝对URL。同时介绍了URL含有参数时该如何处理。

本文参与 腾讯云自媒体分享计划,分享自微信公众号。
原始发表:2017-03-09,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 机器学习与系统 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 说明
  • Entry Point
  • URL结构
  • Relative vs Absolute
  • URL模板
  • 变量
  • 译者说
相关产品与服务
Serverless HTTP 服务
Serverless HTTP 服务基于腾讯云 API 网关 和 Web Cloud Function(以下简称“Web Function”)建站云函数(云函数的一种类型)的产品能力,可以支持各种类型的 HTTP 服务开发,实现了 Serverless 与 Web 服务最优雅的结合。用户可以快速构建 Web 原生框架,把本地的 Express、Koa、Nextjs、Nuxtjs 等框架项目快速迁移到云端,同时也支持 Wordpress、Discuz Q 等现有应用模版一键快速创建。
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档