如何在 API JSON 结果中返回文件？

Question

我正在研究一个 REST API，它返回一个电子书列表。每本电子书都有许多照片和一个 PDF。我有每个图像文件和 pdf 文件的名称和网址。

我应该如何在 REST API 响应中包含此信息？
1. 有房产照片和另一份文件吗？
2. 或者只是说文件并指定文件类型？
3. 或者其他方式？

目前我有以下 JSON：

{
  "ebooks": [
    { 
      "title": "ebook 1"
    },
    { 
      "title": "ebook 2"
    }
  ]  
}

我正在尝试使用一种标准的方法来做到这一点，因此它在我的 API 端点之间保持一致。

Answer 1

您实际上应该只在 API 中返回元数据（如您所描述的那样），并在每条ebook记录中插入指向文件的链接。

来自 API 的响应应类似于以下 JSON：

{
  "ebooks": [
    { 
      "title": "ebook 1",
      "pictures:" [
          "http://myhost/pictures/picture1.jpg",
          "http://myhost/pictures/picture2.jpg",        
          ],
      "document": "http://myhost/ebooks/ebook1.pdf"
    },
    { 
      "title": "ebook 2",
      "pictures:" [
          "http://myhost/pictures/picture3.jpg",
          "http://myhost/pictures/picture4.jpg",        
          ],
      "document": "http://myhost/ebooks/ebook2.pdf"
    }
  ]  
}

这种方法是完全 RESTful 的，并且正是HATEOAS约束建议您所做的：让您的资源可寻址。

您无法使用相同的响应同时返回 JSON 和原始二进制内容，我强烈建议您避免将文件转换为 Base64 字符串并将其返回到 JSON 响应，原因有两个：

1. Base64 编码最多可将文件大小增加 33%
2. 你的API响应将会变得巨大。想象一下，即使您只需要返回 10 条电子书记录（少量）：这意味着您必须将大量数据（pdf、图像等）编码为 Base64。API 的一个简单响应可能会导致浏览器下载数百 MB 的数据。