エンドポイント

すべてのエンドポイントにルートリソースがあります。ルートリソースは、エンドポイントによる作成、更新、削除、またはクエリの対象となるリソースです。エンドポイントに対するすべての呼び出しは、ルートリソースを利用します。

例えば、/common/v1/activities エンドポイントのルートリソースは Activity です。このエンドポイントを使用して、アクティビティの作成、更新、削除、またはアクティビティに対するクエリを実行する可能性があります。

大部分のエンドポイントには、子リソースも含まれています。子リソースは、ルートリソースに関連するリソースです。子リソースによりエンドポイントの使いやすさが向上していますが、ルートリソース関連情報へのアクセスの提供により実現しています。例えば、/common/v1/activities エンドポイントには、子リソースの Notes があります。エンドポイントを以下のために使用できることをこれは意味します。

• 特定のアクティビティ（およびそのアクティビティのみ）に対するクエリ
• 特定のアクティビティおよび関連備考に対するクエリ

エンドポイントに対するすべての呼び出しは、ルートリソースを利用する必要があります。子リソースの使用はオプションです。

インラインおよび包含リソース

子リソースは、インラインリソースまたは包含リソースとして宣言できます。

• インラインリソースは、ペイロードインラインの attributes セクションに出現するリソースであり、他のルートリソースフィールド（Activity リソースの assignedUser フィールドなど）に付随しています。これらのリソースは、デフォルトで応答に含めることができ、fields クエリパラメータによって制御できます。
• 包含リソースは、ペイロードの下部にある included セクションに出現するリソースであり、Activity リソースの Notes などがあります。これらのリソースは、デフォルトで応答に含まれず、included クエリパラメータによって制御する必要があります。

インラインおよび包含リソースの詳細については、GETを参照してください。

操作は一種のアクションであり、呼び出し元アプリケーションがエンドポイントを介してリソースで実行できます。操作は、英単語の動詞またはメソッドでも示されます。システム API は、以下の HTTP 操作のサブセットをサポートしています。

• GET：リソースの要求に使用します。
• POST：リソースの作成に使用します。また、申込の見積作成やクレームの送信などのビジネスアクションの実行にも使用します。
• PATCH：リソースの更新に使用します。
• DELETE：リソースの削除に使用します。

すべてのエンドポイントは、これらの操作の 1 つ以上をサポートしています。Common API での例を次に示します。

• notes/{noteId} エンドポイントは、GET、PATCH、および DELETE をサポートしています。
• /activities エンドポイントは、GET 操作のみをサポートしています。

HTTP 操作は、CRUD 操作（作成、読み取り、更新、削除）用に設計されています。InsuranceSuite アプリケーション内のいくつかのビジネスプロセスは、システム API で使用できますが、オブジェクトの割り当て、オブジェクトの終了、オブジェクトの承認などの操作のいずれにも直にマッピングされていません。一般的に、これらのプロセスをトリガするカスタムアクションは、POST 操作を使用します。

要素およびコレクションへの操作のマッピング

一般的には、次のとおりです。

• GET は、要素またはコレクションに対して実行できます。
• POST をコレクションに対して実行して要素を作成します。
• POST をカスタムアクションに対して実行します（ビジネスアクションを実行するため）。
• PATCH を要素に対して実行します。
• DELETE を要素に対して実行します。

次に例を示します。

操作	実行対象のエンドポイント	行われる操作
GET	/activities	現在のユーザーに割り当てられているすべてのアクティビティを返す。
GET	/activities/{activityId}	指定したアクティビティの詳細を返す。
POST	/activities/{activityId}/notes	指定したアクティビティに新規の備考・経緯を追加する。
POST	/activities/{activityId}/assign	アクティビティをアサインする。
PATCH	/activities/{activityId}	指定したアクティビティの情報を更新する。
DELETE	/notes/{NoteId}	指定した備考・経緯を削除する。

エンドポイントと操作との比較

技術的に言えば、1 つのエンドポイントが複数の操作をサポートしていても、1 つのエンドポイントです。ただし、日常的には、各操作を個別のエンドポイントと呼ぶこともあります。例えば、次について考えてみます。

• GET /common/v1/activities
• POST /common/v1/activities

これは、2 つの操作（GET と POST）をサポートしている 1 つのエンドポイント（/common/v1/activities）です。ただし、日常的には、2 つのエンドポイント（GET /activities エンドポイントと POST /activities エンドポイント）と呼ぶことがあります。

PUT 操作

REST API アーキテクチャには、既存のリソースを変更する 2 つの操作（PATCH と PUT）があります。PATCH は、既存のリソースの一部を変更するために使用します（その他の部分は変更されないままとなります）。PUT は、既存のリソースで内容全体を新しいデータに置換するために使用します。システム API では、PATCH 操作をサポートしていますが、PUT 操作はサポートしていません。InsuranceSuite オブジェクトを変更する操作はほぼすべて、オブジェクトの一部のみを変更しながら、残りの部分はそのまま残すためです。この動作は PATCH には当てはまりますが、PUT には当てはまりません。

すべてのエンドポイントには、パスがあります。パスは URL の一部であり、これを呼び出し元アプリケーションが使用して特定のエンドポイントを特定します。

Cloud API の場合、すべてのパスは以下のパターンで構成されています。

rest/<APIname>/<APImajorVersion>/<endpointName>

例えば、rest/common/v1/activities のパスについて考えてみます。

• common は、エンドポイントが属している API の名前です。
• v1 は、API のメジャーバージョン番号です。
• activities は、エンドポイント名です。

メジャーバージョン番号は、エンドポイントの下位互換性に関する情報を提供します。詳細については、メジャーリリースとマイナーリリースを参照してください。

パスには、特定リソースの参照も含めることができます。例えば、/activities/xc:20/notes のパスは、アクティビティ xc:20 の備考・経緯を参照します。パスに特定リソースの参照を含める場合、{typeId} を使用して汎用パス名を指定します（type はリソースタイプ）。例えば、/activities/xc:20/notes の汎用パスは /activities/{activityID}/notes です。1 つのパスで特定リソースの参照は、パスパラメータと呼ばれます。

大部分のエンドポイントでは、エンドポイント名はリソース名と同じであり、以下の規則と注意事項があります。

• エンドポイントのルートリソースが要素である場合、エンドポイント名の末尾は英単語の単数形名詞（/activity など）またはリソースの参照（/activity/{activityId} など）になります。
• エンドポイントのルートリソースがコレクションである場合、エンドポイント名の末尾は英単語の複数形名詞（/activities など）になります。
• エンドポイントがビジネスアクションを実行する場合、エンドポイント名の末尾は英単語の動詞（/{activityId}/assign など）になります。
• 多くの場合、エンドポイント名はリソース名に似ていますが、同じではありません。
  • エンドポイント名では小文字を使用しますが、リソース名では大文字と小文字を使用します（例えば、/activity エンドポイントのルートリソースは Activity です）。
  • エンドポイント名ではハイフンを使用して語を区切りますが、リソース名ではハイフンを使用しません（例えば、/fixed-property-incidents エンドポイントのルートリソースは FixedPropertyIncident です）。
  • また、エンドポイント名がルートリソース名と異なる場合もあります（例えば、/contacts エンドポイントのルートリソースは ClaimContact です）。