休息 'guidelines' 使 API 设计困难

Question

我正在尝试为我的 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 的单个部门？

Answer 1

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

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

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

例如...

DELETE company/departments/58491

通过使用标识符而不是部门名称，可以避免 URI 中出现空格，这是不可取的。对于部门名称，我假设您指的是用户友好的显示名称，例如 "Human Capital Management."

Answer 2

一个URL由几个部分组成：

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

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

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

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

就 REST 而言，

ftp://127.0.0.1/E280F814-1524-41D5-8735-43D8414AE242 非常好 URL。

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

也就是说，针对 URL 中的参数的建议是因为有时缓存不会正确缓存参数化的 URL。因此 /company/department/12345 优于 /company/department?id=12345.

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

所以这听起来像是一个简单的错误传达，你正在战斗。尽量不要过分强调它。无论如何，当真正重要的是资源及其表示形式时，URL 命名被压得太重了。

Answer 3

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

DELETE company/departments/58491

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

希望对你有帮助，蒂埃里

Rest 'guidelines' make the API design difficult