Question

我正在设计一个有点RESTful的API，并且数据模型相对复杂且规范化。 API的返回数据应该有多简单？

更好的做法是将外键或ID替换为相关表中的实际数据，还是更好的做法是返回数据库中的内容并提供API方法将这些ID转换为可用内容？或者......除了可用的数据之外，提供ID更好吗？

以下是返回数据中数据库中原始数据的示例：

<books>
  <book-id>935</book-id>
  <book-author-id>64</book-author-id>
  <book-genre-id>5</book-genre-id>
</books>

以下是返回可用内容的示例：

<books>
  <book-name>Steve Jobs</book-name>
  <author-name>Walter Isaacson</author-name>
  <book-genre-name>biography</book-genre-name>
</books>

Answer 1

这实际上取决于您的数据将如何使用。通常，只要您需要深入细节，就需要提供可以使用的URL或ID。

对于您的示例，标题不是您可能需要提供更多详细信息的内容，因此您可能只是直接包含它。类型也不需要更多细节，但人们可能想要获取该类型的所有其他书籍。

作者几乎肯定是你想要更多细节的东西，包括传记信息以及他们寻找其他书籍。不仅如此，虽然您的类型字段不太可能包含重复的名称，但您的作者肯定会这样做。

作者本身应该是一种资源。流派应该如此。两者都有链接。

对于真实的API设计，您需要对资源进行非规范化处理。加入是http的地狱。假设几乎所有提取图书的人都需要作者姓名，您应该将其包含在图书资源中。他们可能还需要有关作者的其他信息，例如他的照片。

因此，对于您的示例API，我们已经达到了类似的目标......

<books>
  <title>Steve Jobs</book-name>
  <author href="http://example.com/author/64">
        <name>Walter Isaacson</name>
        <photo>http://images.example.com/author/64/photo</photo>
    </author>
  <genre href="http://example.com/genre/5">biography</genre>
</books>

不要对开发人员如何使用您的API做出太多假设。关于API的一个好处是开发人员开始使用它来创建你从未想过的东西。给他们原始工具，看看会发生什么样的真棒。

Answer 2

我一般会说您的API应该符合API用户的要求。特别是，“暴露数据模型”并不是一个好目标。实际上，您可能会公开数据模型的某些部分（可能是简化的），以满足要求。但是，无论是否公开外键都是一个全面的答案，这完全取决于要求。

与数据模型相比，API的返回数据应该被简化多少？

2 个答案: