Question

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

我正在使用Python 2.7.3，Django 1.5和带有PostgreSQL 9.1的django-rest-framework 2.2.4

我需要/想要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 Framework的“可浏览性”，但它似乎并没有解决这类问题，而且我今天早些时候与Tom Christie在IRC上进行了非常好的聊天，他没有我真的有答案在这里做什么（或者我从来没有明白我的问题）。

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

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

 pos-location-url: '/pos_location/'

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

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

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

最后的注意事项：我得到的事实是，我并不真的希望在这里“泄漏”抽象，并让我的数据库通过API层达到峰值，但事实仍然是这个现有<存在一个foreign_key约束/ em>数据库和任何没有有效pos_location_type_id的插入都会引发错误。

另外，我不打算打开URI与ID辩论。用户是否必须使用pos_location_type_id int值或URI与此讨论无关。在任何一种情况下，他们都不知道该送我什么。

Answer 1

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

另一方面，我也采用了这种方式，而不是像RESTful一样。假设你在纽约有一个位置，POST可能是这样的：

POST /pos/new_york/

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

通过这种方式，您可以避免请求数据中的pos_location_type，您可以以编程方式将其映射到有效ID。

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

1 个答案: