REST - 如何设计带有复合键的 URI? [英] REST - how design an URI with composite keys?

问题描述

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

I have a question about how design a resource URI with composite keys.

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

I have a resource called freight that has 4 keys/ids: partner ID, initial zipcode, final zipcode and weight.

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

Actually my resource was designed to have an incremental ID generated by database, but this approach is not so good to API consumers, for example if a consumer/partner needs to update a freight info they have to do:

获取运费?initialZipcode={VALUE}&finalZipcode={VALUE}&weight={VALUE}

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

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

The response of the operation above would be the freight ID, so finally they can update the info:

PUT 运费/{ID}

PUT freight/{ID}

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

The partner ID is implicit by the authentication mechanism.

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

For me it seems strange force the partners to obtain the freight ID before update the info.

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

So my question is: how can I design this URI?

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

PUT freight/initialZipcode/{VALUE}/finalZipCode/{VALUE}/weight/{VALUE}

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

Have I to consider the design above?

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

Another question: is a good practice to embedded the partnerId in authentication mechanism? I know the pros (easy to consumers) and cons (cache, impossibility to share an URI, etc), but I don't know if generally is a good or bad practice.

谢谢！

推荐答案

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

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

Query parameters are part of the resource identification too.

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

Path parameters are useful for defining resources that fit nicely in a hierarchy. In your case the resource doesn't fit well in a hierarchy, so don't try and squeeze the parameters into path segments.

唯一的挑战是当客户端重新排列查询参数的顺序时该怎么做.你把它当作同一个资源，还是404?如果您没有缓存 GET 响应，那么这可能无关紧要.

The only challenge is what to do when the client re-arranges the order of the query params. Do you you treat it as the same resource, or do you 404? If you are not caching the GET responses then it probably doesn't matter.

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

If you provided your client with a URI template for them to fill in then there is less chance that they will give you the params in the wrong order.

另一种选择，如果您采用最初的建议，则您的 GET 将重定向和位置标头返回到带有货运 ID 的 URI.例如

The other option, if you go with your original suggestion is that your GET returns a redirect and a Location header to a URI with the freight ID. e.g.

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

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

By doing this, your client doesn't have to know anything about the freight ID, it can just grab the location header, and follow the redirect to do a GET, or do a PUT directly against whatever URI is in the Location header. This means that if you decide you don't like exposing the ID in the future, you can change the URI without breaking any clients.

这篇关于REST - 如何设计带有复合键的 URI?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！