20、API 自定义方法与长运行操作全解析

API 自定义方法与长运行操作全解析

自定义方法概述

在 API 设计中，自定义方法是对标准方法的重要补充。它在很多方面与标准方法相似，但也存在一些显著的差异。

自定义方法的实现

• HTTP 请求格式 ：自定义方法的 HTTP 请求格式与标准方法有所不同。标准方法依赖请求路径和 HTTP 方法的组合来指示方法的行为，而自定义方法由于 HTTP 动词的限制，有其特殊的格式。自定义方法的 HTTP 方法几乎总是 POST，虽然也可能使用 GET 或 DELETE，但相对较少。例如，对于火箭发射的自定义方法，其 HTTP 请求格式如下：

P     /  rockets / 1234567  :  launch
OST
HTTP
method
Resource
Action

在这个例子中，使用冒号（:）来分隔资源和自定义操作，避免了使用斜杠可能带来的歧义。
- 命名约定 ：自定义方法的 RPC 名称应遵循动词后跟名词的命名约定，如 LaunchRocket 或 ArchiveDocument ，这与标准方法的命名约定一致。同时，应避免使用介词，如 “with” 或 “for”，以确保自定义方法的规范性。

自定义方法的副作用

标准方法的目标是作为访问和操作资源数据的有限机制，其关键原则是只做其声明的事情，不触发额外的后台操作。而自定义方法则没有这样