如何定义 API 端点答案

【问题标题】：How to define API Endpoints如何定义 API 端点
【发布时间】：2019-02-18 21:53:41
【问题描述】：

我正在设计一个 API 来请求有关索引的信息，其中包含遵循某种 JSON 格式的数据。

目前我只有类型构建的数据，但可能会出现其他类型，即：：

example data #1 :
"type": "building",
"id": "1",
"address" : "1 test",
...
"buildingType": "private",
"buildingSubType: "house"

example data #2 :
"type": "building",
"id": "2",
"address" : "100 test",
...
"buildingType": "corporate",
"buildingSubType: "restaurant"

example data #3 :
"type": "building",
"id": "3",
"address" : "200 test",
...
"buildingType": "government",
"buildingSubType: "hr services"

当我开始时，数据更简单，类型和子类型更少，因此构建 API 端点很简单，但随着时间的推移变得越来越复杂，我想将我的 api 定义为在新数据到来时更具前瞻性

关于 REST 和未来的 API 文档，这是我得到并想要验证的：

/buildings - Returns all buildings entries
/buildings/{id} - Returns a specific building entry
/buildings/buildingTypes - Returns all buildingTypes
/buildings/buildingTypes/{name} - Returns building entries with the specified buildingType
/buildings/buildingTypes/{name}/buildingSubTypes - Returns all buildingSubTypes for the specified buildingType
/buildings/buildingTypes/{name}/buildingSubTypes/{name} - Returns building entries with the specified buildingType and buildingSubType

对于 2，我将添加查询字符串参数以更精确地过滤，例如： /buildings/buildingTypes/corporate?states=NY /buildings/buildingTypes/corporate/buildingSubTypes/restaurant?state=NY

【问题讨论】：

这个 url 结构看起来很合理。一个小问题是您不能拥有一个 id 为“buildingTypes”的“建筑物”。因为它们有点生活在同一个命名空间中，所以我个人会选择“buildingTypes”来生活在顶级命名空间中，而不是在“/buildings/”下

标签： rest api endpoint

【解决方案1】：

关于 REST 和未来的 API 文档，这是我得到并想要验证的内容

REST 不关心您的 URL 使用什么拼写，也不关心您如何组织资源层次结构。

URL 拼写约定只是为了方便人们使用——它们对于 API 的正确性并不比变量名称的拼写更重要。

【讨论】：