用于 POST 和 PUT 的 RESTful API 和外键处理

Question

我正在帮助为一个现有数据库开发一个新的 API。

我正在使用 Python 2.7.3、Django 1.5 和 django-rest-framework 2.2.4 和 PostgreSQL 9.1

我需要/想要好的 API 文档，但我人手不足，我讨厌编写/维护文档（我的许多缺陷之一）。

我需要允许 API 的使用者添加新的“POS”（销售点）位置。在 Postgres 数据库中，有一个从 pos 到 pos_location_type 的外键。所以，这是一个简化的表结构。

pos_location_type(
  id serial,
  description text not null
);

pos(
   id serial,
   pos_name text not null,
   pos_location_type_id int not null references pos_location_type(id)
);

所以，为了让他们发布一个新的 pos，他们需要给我一个“pos_name”和一个有效的 pos_location_type。所以，我整个周末都在阅读这些东西。有很多争论。

我的 API 使用者如何知道 pos_location_type 是什么？或者在这里传递什么值？

看来我需要告诉他们在哪里可以获得有效的 pos_locations 列表。比如：

GET /pos_location/

简要说明一下，pos_location_type 描述的示例可能是：('school', 'park', 'office')。

我真的很喜欢 Django REST 框架的“可浏览性”，但是，它似乎没有解决这类问题，实际上我今天早些时候在 IRC 上与 Tom Christie 进行了非常愉快的交谈，他没有'真的没有关于在这里做什么的答案（或者也许我从来没有把我的问题说清楚）。

我看过 Swagger，这是一个非常酷/有趣的项目，但请在他们的 demo here 上查看他们的“宠物”资源。请注意，这与我需要做的非常相似。要添加新宠物，您需要传递一个类别，他们将其定义为类 Category(id: long, name: string)。消费者如何知道要在这里传递什么？什么是有效身份证？还是名字？

在 Django rest 框架中，我可以定义/覆盖 OPTION 调用中返回的内容。我想我可以在这里建立自己的小“系统”并返回一些信息，例如：

 pos-location-url: '/pos_location/'

在通用形式中，它是：{resource}-url: '/path/to/resource_list'

这对文档方面来说有点用，但我不确定这是否真的是一个很好的编程解决方案。如果我更改资源位置怎么办。这意味着我的消费者需要以编程方式制作和 OPTIONS 调用资源来找出所有关系。也许不是一件坏事，但感觉有点奇怪。

那么，人们如何处理这种事情呢？

最后的说明：我知道我真的不想要一个“泄漏”的抽象，并让我的数据库通过 API 层达到峰值，但事实仍然是这个 existing 数据库和任何没有有效 pos_location_type_id 的插入都会引发错误。

另外，我并不是要展开 URI 与 ID 的辩论。对于 this 的讨论，用户是否必须使用 pos_location_type_id int 值或 URI 无关紧要。无论哪种情况，他们都不知道该给我寄什么。

Answer 1

我过去曾使用过这种东西。我认为有两种方法可以解决这个问题，第一种方法是您已经说过的，允许 API 用户的端点知道pos_location_type 的类似 id 的值是什么。许多 API 这样做是因为从您的 API 开发的人必须阅读您的文档并且知道从哪里获取 pos_location_type 值。最终用户不必担心这一点，因为他们的界面可能会显示文本值的下拉列表。

另一方面，我的工作方式也不是很像 RESTful。假设您在纽约有一个位置，POST 可能是这样的：

POST /pos/new_york/ 

您可以通过规范化文本来处理 /pos/(location_name)/，然后只需在数据库中搜索值或某些相似性，如果位置不存在，则只需创建一个新位置。如果用户可以添加新地点，如果不能，那么用户必须知道存在哪些固定地点，这也是我们所处的第一种情况。

这样您就可以避免在请求数据中出现pos_location_type，您可以通过编程将其映射到有效的 ID。