哪种 API 路由设计符合最佳实践？ [关闭]

Question

在为一个用 C# 编写的 ASP.Net Web API 应用程序设计 RESTFul 的 URI 时，我发现自己陷入了困境，什么是最佳实践。

取下面的伪代码。

public class File{
 public int ID {get;set;}
 public string Name {get;set;
}

public class X {
 public int ID {get;set;}
 public string Name {get;set;}
 public List<File> Files {get;set;}
}

public class Y  {
 public int ID {get;set;}
 public string Name {get;set;}
 public List<File> Files {get;set;}
}

public class Z  {
 public int ID {get;set;}
 public string Name {get;set;}
 public List<File> Files {get;set;}
}

现在，如果我想要一个特定的文件，我会调用类似：

/api/Files/{ID}

现在，如果我想要与另一个资源相关的文件，我是否要创建路由：

/api/X/{xID}/Files
/api/Y/{yID}/Files
/api/Z/{zID}/Files

或者我是否可以这样做：

/api/Files/X/{xID}
/api/Files/Y/{yID}
/api/Files/Z/{zID}

在维护方面，后一种选择似乎更合适；与文件有关的任何内容都包含在同一个控制器中。

虽然前一个选项对我来说似乎更明确，但不知何故，这意味着在整个控制器中传播类似的调用

或者，有什么不同的方法可以解决吗？

Answer 1

有许多指南解释了如何设计 API 的一些最佳实践。归根结底，设计者需要提供一个适合开发者的 API。

在这种情况下，您谈论的是两个不同的端点：(1) Files 端点，以及 (2) 包含文件的其他一些资源（我们称之为 Folders）。

一般而言，您的 URL 应包含 API 的版本（例如“v1”）和资源端点（例如“文件”）。因此，您的 URL 将形成如下：

1. /api/v1/files
2. /api/v1/folders

对于查询，您需要确保坚持使用一些标准的查询字符串参数（例如/api/v1/files?id=blah），而不是用斜杠或其他字符分隔查询参数。

对于另一个端点 (folders)，在初始 get 中包含文件（或至少是标识符）可能是有意义的，或者要求调用者请求特定的 @ 可能是有意义的987654330@ out of the set 在提供此信息之前。

当开发人员想要在folder 中获取files 时，通过要求开发人员找出复杂的 URL 来拆分对象是不合适的。如果在查询folder 时不希望包含files，那么最好关闭关系并允许客户端使用查询在给定的folder 内查询files files 端点上的字符串语法。

一些有用的链接：

• 18F API Standards
• White House API Standards
• This article

Answer 2

我认为这是使用 json 引用的情况

http://json-spec.readthedocs.org/en/latest/reference.html

我不确定这个例子是否特别清楚，但本质上你提供了 /Files/fileId 接口，然后在你的 X/Y/Z 对象中而不是包含你引用它的文件

{
    "Files" : [{"$ref" : "/file/myFileId"}]
}

如果你想提供一个返回多个未分组资源的接口，恭喜你遇到了 REST 的限制，请使用 POST

----重新计算：

详细说明“使用 POST”

RESTful 方法是使用 GET 来“获取”资源，但是，当您必须传递多个 id 时，即 GET Files?id=1&id=2&id=3..... 您会遇到 url 的长度限制.这会迫使您使用 POST Files BODY id=1&id=2&id=3..... （或者更可能是一些 json 请求结构）关于这个主题有几个类似的问题，关于堆栈溢出的各种方法