タイプ プロバイダの追加のためのベスト プラクティス

このページでは、新しい API を作成してタイプ プロバイダとして Deployment Manager に追加する場合や、既存の API をタイプ プロバイダとして追加する場合のベスト プラクティスについて説明します。

Deployment Manager により、API をタイプ プロバイダとして追加し、API リソースを設定で呼び出すことができるタイプとして公開できます。プロセスを容易にするために、API の設定時または作成時にこれらのベスト プラクティスを使用してください。

新しい API の構築

Deployment Manager と統合する新しい API を構築する場合、次のようなベスト プラクティスを使用します。

標準の作成、読み取り、更新、削除（CRUD）メソッドを使用し、カスタム メソッドを使用しない

できる限りカスタム メソッドの作成を避けます。GET、POST、PUT、DELETE などの標準 REST メソッドを使用します。これらのメソッドは Deployment Manager で認識され、自動的にマッピングできます。

検出のための API の場合、次のマッピングに従って API メソッドに名前を付ける必要があります。

REST メソッド 推奨される API の命名
POST create または insert
GET get
PUT update
DELETE delete

OpenAPI 仕様の場合、API メソッドに標準 REST メソッドとは異なる名前を付けることはできません。

予測可能なリソースパスを使用する

OpenAPI 仕様の場合、Deployment Manager は RESTful インターフェースを識別する 2 つの動作をサポートしています。そのうちの 1 つはリソースに対するすべての REST メソッドが同じリソースパスに属している場合です。

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

メソッドを区別する必要がある場合、同じリソースパスを使用します。たとえば、以下は同じ /foo リソースを参照しているために有効です。

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

ただし、以下は Deployment Manager のビューから 2 つの異なるリソースを参照するため、無効です。

/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 メソッドで必要とされるサーバーによって生成される値がある場合、入力マッピングを設定して、サーバーによって生成された値を取得して、それを各リクエストにマッピングする必要があります。

次のステップ