休息“指南”使 API 设计变得困难答案

【问题标题】：Rest 'guidelines' make the API design difficult休息“指南”使 API 设计变得困难
【发布时间】：2015-02-22 21:28:30
【问题描述】：

我正在尝试为我的 Rest 服务创建 API，但我正在努力遵循我尝试遵循的设计规则。一般来说，我试图遵循（除其他外）这些准则：

现在，我必须对以下内容进行建模：

我正在尝试这样的事情：

GET company/departments
GET company/departments/<depName>
DELETE company/departments
DELETE company/departments  {body: department name}

以上内容遵循我提到的准则，但我真的不认为生成的 URI 是好的。尤其是第四个，它的工作不同，并且与第三个具有相同的 URI。

这对我来说是一个常见的问题，我在设计 REST 服务时遇到过很多次。结果是我总是打破一些设计原则来实现我想要的或制作更丑陋的 URI（例如：DELETE company/departments/department）。

所以实际的问题是：

在我的设计中，如何删除具有类似 Restfull URI 的单个部门？

【问题讨论】：

【解决方案1】：

一个 URL 由几个部分组成：

http://example.com/company/departments/12345?arg1=this&arg2=that

http: 是方案。 //example.com 是主机。 /company/departments/12345 是路径，?arg1=this&arg2=that 是查询字符串，由两个参数组成：arg1 和 arg2。还有一个方面，叫做矩阵参数，这里不讨论了。

当 REST 谈到 URL 时，它指的是整个事物。不是它的一部分。对于 REST，整个 URL 被视为一个不透明的 blob。

这意味着 REST 不关心任何特定部分：方案、主机、路径或参数。

ftp://127.0.0.1/E280F814-1524-41D5-8735-43D8414AE242 就 REST 而言是一个完美的 URL。

因此，就 REST 而言，它不会说明您在 URL 中使用的路径或是否使用参数。

也就是说，针对 URL 中的参数的建议是因为有时缓存无法正确缓存参数化的 URL。因此，/company/department/12345 的偏好高于 /company/department?id=12345。

路径中的12345 不是参数。它是资源的名称。就像上面的starwars.mp4不是参数一样，E280F814-1524-41D5-8735-43D8414AE242也不是。他们只是名字。唯一真正关心的人是人。计算机不在乎，互联网不在乎，REST 不在乎。对他们来说，这只是一点点。

所以这听起来像是一个简单的误解，你正在战斗。尽量不要过分强调它。无论如何，当资源及其表示实际上很重要时，URL 命名的权重就太大了。

【讨论】：

【解决方案2】：

RESTful URI 的更好设计是使用资源标识符。在这种情况下，资源是部门。

因此您的 URI 可能如下所示：

GET company/departments  
GET company/departments/<department-id>  
DELETE company/departments  
DELETE company/departments/<department-id>

例如...

DELETE company/departments/58491

通过使用标识符而不是部门名称，可以避免 URI 中出现不受欢迎的空格。对于部门名称，我假设您的意思是用户友好的显示名称，例如“人力资本管理”。

【讨论】：

【解决方案3】：

我同意。您应该使用如下 URL 来删除部门。这样的 URL 标识了一个部门，可以用来对其执行 HTTP 操作。不要在请求的负载中提供部门 ID 或名称。

DELETE company/departments/58491

以下链接可以为您提供有关设计 RESTful 服务的更多详细信息：https://templth.wordpress.com/2014/12/15/designing-a-web-api/。

希望对你有帮助蒂埃里

【讨论】：