2

我正在帮助为现有数据库开发新的 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，这是一个非常酷/有趣的项目，但请在此处的演示中查看他们的“宠物”资源。请注意，这与我需要做的非常相似。要添加新宠物，您需要传递一个类别，他们将其定义为类 Category(id: long, name: string)。消费者如何知道要在这里传递什么？什么是有效身份证？或名字？

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

 pos-location-url: '/pos_location/'

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

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

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

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

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

4

1 回答 1

0

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

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

POST /pos/new_york/

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

这样您就可以避免pos_location_type在请求数据中，您可以以编程方式将其映射到有效 ID。

于 2013-03-18T18:05:33.577 回答