在REST调用中使用URI作为参数值的最佳实践

Question

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

例如:

我有一个资源,让我获得Java类.然后,以下请求将为我提供所有Java类:

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

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

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

该请求将返回我Vector,ArrayList以及CollectionJava类的所有其他子类.

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

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/.这会给我以下可能性:

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

另一种可能性是完全删除类别名并始终为参数值添加前缀,http://example.org/api/v1/class/因为这是我唯一支持的内容.这会将所有子类型的请求Collection转换为:

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

原始请求URI的这些"简化"是否仍然符合REST架构的原则？或者我刚刚离开了深渊？

ADDENDUM:URI中可能同时有多个过滤器.可以是不同的参数,也可以是单个参数的值列表.按照"实现接口X和/或接口Y的所有类"或"实现接口X并且在ABC包中的所有类"的方式思考(其中包也可以像URI一样寻址http://example.org/api/v1/packages/a/b/c)

Answer 1

我会去做：

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

返回 RESTful API 中其他条目的链接列表，每个直接子类都有一个链接。我还将将该信息作为返回描述符的一部分提供：

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

（这还包括指向前面特定查询的链接。）