添加类型提供程序的最佳做法

本页面介绍了创建新 API 并将其添加到 Deployment Manager 作为类型提供程序，或者添加现有 API 作为类型提供程序的最佳作法。

Deployment Manager 允许您添加 API 作为类型提供程序，以公开 API 资源，作为可在其配置中调用的类型。为了使该流程更轻松，请在配置或创建 API 时使用这些最佳作法。

构建新 API

如果要构建拟与 Deployment Manager 集成的新 API，请使用这些最佳作法。

使用标准的创建、读取、更新和删除 (CRUD) 方法并避免使用自定义方法

尽可能避免创建自定义方法。坚持使用标准的 REST 方法，如 GET、POST、PUT 和 DELETE 方法。这些方法可被 Deployment Manager 识别，也可以自动映射。

对于 Discovery API，您应该根据以下映射命名 API 方法：

REST 方法 推荐的 API 命名
POST create 或 insert
GET get
PUT update
DELETE delete

对于 OpenAPI 规范，您不能采用不同于标准 REST 方法的方式命名 API 方法。

使用可预测的资源路径

对于 OpenAPI 规范，Deployment Manager 支持标识 RESTful 接口的两种行为。首先，如果资源的所有 REST 方法都属于同一资源路径：

/foo/{name}
  post:
  get:
  delete:
  put:

如果您必须分离方法，请使用相同的资源路径。例如，以下内容有效，因为它引用了同一个 /foo 资源：

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

但是，以下内容无效，因为对 Deployment Manager 而言，它指的是两个不同的资源：

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

在极少数情况下，您可能想按照以下方式为资源路径命名：

foo/create
  post:

foo/delete
  delete:

这在 Deployment Manager 视图中无效，因为它无法标识 RESTful 接口。

在界面上使用一致的命名

在 POST 和 PUT 方法之间保持输入和路径名相同。这也适用于参数值。也就是说，不同方法中的参数值所用的语法需相同。

例如，如果 POST 请求的正文中有一个名为 email 的参数，则不要将 PUT 请求中的同一个参数命名为 emailAddress。

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

如果必须添加此类行为，请通过设置高级 API 选项告知 Deployment Manager 如何处理此行为。

另外，请对 POST 和 PUT 方法使用相同的请求正文。对于 GET 和 DELETE 方法，仅路径适用，因为这些方法没有请求正文。

集成现有 API

集成现有 API 的过程可能变化很大，具体取决于 API。因此，没有一套具体的最佳实践可以广泛应用于所有 API。在考虑集成现有 API 的方法时，以下列出了一些一般性建议，可能会对您有所帮助。

  • 对非 RESTful API 使用 API 封装容器。

    如果现有 API 不是 RESTful API，则可以创建仅公开 REST 方法的 API 封装容器。

  • 如果 API 几乎是 RESTful，请标识并更新 API。

    如果您的 API 几乎是 RESTful 且只有少数非 REST 行为，您可以更新 API 以解决这些行为。

  • 服务器生成值始终需要输入映射。

    如果您的 API 具有 API 方法所需的服务器生成值，则需要设置输入映射以获取服务器生成值，并针对每个请求映射该值。

后续步骤