在 REST 调用中使用 URI 作为参数值的最佳实践 [英] Best practices on using URIs as parameter value in REST calls

问题描述

我正在设计一个 REST API，其中一些资源可以通过查询参数进行过滤.在某些情况下，这些过滤器值可能是来自同一 REST API 的资源.这会导致 URI 变得冗长且不可读.虽然这本身并不是什么大问题，因为 URI 旨在以编程方式创建和操作，但它会导致一些痛苦的调试.我正在考虑允许将 URI 的快捷方式用作过滤器值，我想知道根据 REST 架构是否允许这样做，以及是否有任何最佳实践.

I am designing a REST API where some resources can be filtered through query parameters. In some cases, these filter values would be resources from the same REST API. This makes for longish and pretty unreadable URIs. While this is not too much of a problem in itself because the URIs are meant to be created and manipulated programmatically, it makes for some painful debugging. I was thinking of allowing shortcuts to URIs used as filter values and I wonder if this is allowed according to the REST architecture and if there are any best practices.

例如:

我有一个资源可以获取 Java 类.然后下面的请求会给我所有的 Java 类:

I have a resource that gets me Java classes. Then the following request would give me all Java classes:

GET http://example.org/api/v1/class

假设我想要 Collection Java 类的所有子类，那么我将使用以下请求:

Suppose I want all subclasses of the Collection Java class, then I would use the following request:

GET http://example.org/api/v1/class?has-supertype=http://example.org/api/v1/class/collection

该请求将返回我 Vector、ArrayList 和 Collection Java 类的所有其他子类.

That request would return me Vector, ArrayList and all other subclasses of the Collection Java class.

虽然那个 URI 很长.我已经可以通过允许 hs 作为 has-supertype 的别名来缩短它.这会给我:

That URI is quite long though. I could already shorten it by allowing hs as an alias for has-supertype. This would give me:

GET http://example.org/api/v1/class?hs=http://example.org/api/v1/class/collection

另一种允许更短 URI 的方法是允许 URI 前缀的别名.例如，我可以将 class 定义为 URI 前缀 http://example.org/api/v1/class/ 的别名.这会给我以下可能性:

Another way to allow shorter URIs would be to allow aliases for URI prefixes. For example, I could define class as an alias for the URI prefix http://example.org/api/v1/class/. Which would give me the following possibility:

GET http://example.org/api/v1/class?hs=class:collection

另一种可能性是完全删除类别名并始终使用 http://example.org/api/v1/class/ 作为参数值的前缀，因为这是我唯一支持的.这会将对于 Collection 的所有子类型的请求变成:

Another possibility would be to remove the class alias entirely and always prefix the parameter value with http://example.org/api/v1/class/ as this is the only thing I would support. This would turn the request for all subtypes of Collection into:

GET http://example.org/api/v1/class?hs=collection

原始请求 URI 的这些简化"是否仍然符合 REST 架构的原则?还是我刚刚走到了尽头?

Do these "simplifications" of the original request URI still conform to the principles of a REST architecture? Or did I just go off the deep end?

附录:URI 中可能同时有多个过滤器.作为不同的参数，或作为单个参数的值列表.沿着实现接口 X 和/或接口 Y 的所有类"或实现接口 X 并在包 ABC 中的所有类"的思路思考(其中包也可以寻址到像 http://example.org/api/v1/packages/a/b/c)

ADDENDUM: There might be more than one filter in the URI at once. Either as different parameters, or as a list of values for a single parameter. Think along the lines of "All classes that implement Interface X and/or Interface Y" or "All classes that implement Interface X and are in package A.B.C" (where packages would also be addressable to a URI like http://example.org/api/v1/packages/a/b/c)

推荐答案

我会去做:

GET http://example.org/api/v1/class/java.util.Collection/subclasses

返回指向 RESTful API 中其他条目的链接列表，每个直接子类对应一个.我还会将该信息作为以下返回的描述符的一部分提供:

return a list of links to other entries in your RESTful API, one for each direct subclass. I'd also make that information available as part of the descriptor returned by:

GET http://example.org/api/v1/class/java.util.Collection

(这还包括指向前面特定查询的链接.)

(That would also include a link to the preceding specific query.)

这篇关于在 REST 调用中使用 URI 作为参数值的最佳实践的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！