API 入门 (22) 转换目标为API——资源路径

往期文章：

1. 找出资源及其关系
2. 分析资源的操作
3. 设计资源路径
4. 表示为 HTTP 方法

通过分析 API 目标表格，我们发现了两个资源：目录和自行车。目录资源是集合资源，包含了自行车资源。我们该如何在 REST API 中表示他们呢？

路径规则

坦白地说，有效的 REST 路径只有一条规则：必须是唯一的。我们可以使用 /cat 或者 /catalog 表示目录的路径，只要他们是唯一的，不和其他路径相同，就是有效的 REST 路径。

你肯定发现了问题。虽然 /cat 可能是个有效路径，但是，对于第一次见到他的用户，很难猜到他代表什么资源。别忘了，REST API 的设计要以用户为中心。那么，资源路径的设计，要让用户很容易想到其表示的资源。

在前面的分析中，我们知道，目录资源是自行车资源的集合，目录资源包含自行车资源。在表示一个自行车资源时，我们有下面两个选择：

1. /catalog/{bikeId}
2. /bikes/{bikeId}

{bikeId} 是路径中的变量，称为路径参数。我们在访问上面的路径时，需要使用实际的自行车的标识，替换 {bikeId} ，就能访问相应的自行车资源了。

这两个资源路径哪个更好呢？这次有点儿伯仲难分了。那么，我们就制定几个规则，帮助我们设计资源路径：

1. 资源路径必须是唯一的
2. 资源路径使用复数表示集合资源
3. 资源路径要能表示资源间的关系

因此，/bikes/{bikeId} 更符合我们的规则。

路径表示

经过上面的讨论，我们的资源路径也就可以写出来了：

1. 目录资源：/bikes
2. 自行车资源：/bikes/{bikeId}

小结

在设计资源路径时，我们仍然要坚持已用户为中心的原则。同时，遵守资源路径设计规则，始终保持对用户的友好性和一致性。