REST - 如何设计带有复合键的 URI？

Question

我有一个关于如何使用复合键设计资源 URI 的问题。

我有一个名为 cargo 的资源，它有 4 个键/ID:合作伙伴 ID、初始邮政编码、最终邮政编码和重量。

实际上，我的资源被设计为具有由数据库生成的增量 ID，但是这种方法对 API 消费者来说不是很好，例如，如果消费者/合作伙伴需要更新他们必须执行的 cargo 信息:

GET 运费?initialZipcode={VALUE}&finalZipcode={VALUE}&weight={VALUE}

上面操作的响应是 cargo ID，所以最后他们可以更新信息:

PUT 运费/{ID}

合作伙伴 ID 是由身份验证机制隐含的。

对我来说，强制合作伙伴在更新信息之前获取 cargo ID 似乎很奇怪。

所以我的问题是:我该如何设计这个 URI？

PUT 运费/initialZipcode/{VALUE}/finalZipCode/{VALUE}/weight/{VALUE}

我需要考虑上面的设计吗？

另一个问题:将 partnerId 嵌入身份验证机制是一种好习惯吗？我知道优点(对消费者来说很容易)和缺点(缓存、无法共享 URI 等)，但我不知道通常是好的还是坏的做法。

谢谢!

Answer 1

没有错

PUT freight?initialZipcode={VALUE}&finalZipcode={VALUE}&weight={VALUE}

查询参数也是资源标识的一部分。

路径参数对于定义非常适合层次结构的资源很有用。在您的情况下，资源不能很好地适应层次结构，因此不要尝试将参数压缩到路径段中。

唯一的挑战是当客户端重新排列查询参数的顺序时该怎么做。您是否将其视为相同的资源，还是 404？如果您没有缓存 GET 响应，那么它可能并不重要。

如果您为您的客户提供了一个 URI 模板供他们填写，那么他们以错误顺序为您提供参数的可能性就较小。

另一种选择是，如果您采用最初的建议，您的 GET 会将重定向和 Location header 返回到带有 cargo ID 的 URI。例如

GET freight?initialZipcode={VALUE}&finalZipcode={VALUE}&weight={VALUE}
=> 
302 See Other
Location:  freight/1232321322

通过这样做，您的客户端不必知道有关 cargo ID 的任何信息，它可以只获取 location header ，然后按照重定向执行 GET，或者直接针对 Location header 中的任何 URI 执行 PUT。这意味着，如果您决定以后不希望公开 ID，则可以更改 URI 而不会破坏任何客户端。