api - 用于高级搜索/过滤的 .Net Web API URL 约定

Question

我对 Microsoft 的 REST 和 WebAPI 比较陌生。我们正在实现一个集线器 REST 服务，它将容纳多种类型的对象获取和设置。作为该项目的负责人，我的任务是提出我们正在使用的正确 Uri 设计。我想知道对 war 有什么想法更好。是的，我没有使用“标准”这个词，而是专门分阶段进行的。

以下是我和我的团队目前正在娱乐的选项:

Http://servername/API/REST/Ldap/AD/employees?username=jsmith 
Http://servername/API/REST/Ldap/AD/employee/UserName?searchTerm=jsmith (this seems RPC to me)
Http://servername/API/REST/Ldap/AD/employees/getusername?searchterm?jsmith

我们还创建了一个 Soap 版本，因此其余的都在 Uri 中。

感谢您的输入

Answer 1

我建议你看看Web API Design来自布赖恩·穆洛伊。在搜索和过滤方面，他有几条建议。

简化关联 - 扫除“?”下的复杂性

Most APIs have intricacies beyond the base level of a resource. Complexities can include many states that can be updated, changed, queried, as well as the attributes associated with a resource. Make it simple for developers to use the base URL by putting optional states and attributes behind the HTTP question mark. Keep your API intuitive by simplifying the associations between resources, and sweeping parameters and other complexities under the rug of the HTTP question mark.

搜索提示

While a simple search could be modeled as a resourceful API (for example, dogs/?q=red), a more complex search across multiple resources requires a different design. If you want to do a global search across resources, we suggest you follow the Google model:

Global search

/search?q=fluffy+fur

Here, search is the verb; ?q represents the query.

Scoped search

To add scope to your search, you can prepend with the scope of the search. For example, search in dogs owned by resource ID 5678

/owners/5678/dogs?q=fluffy+fur

Notice that the explicit search has been dropped from the URL and instead it relies on the parameter 'q' to indicate the scoped query.

分页和部分响应

Support partial response by adding optional fields in a comma delimited list.

/dogs?fields=name,color,location

Use limit and offset to make it easy for developers to paginate objects.

/dogs?limit=25&offset=50