要求ペイロードの設計

必須フィールド

必須フィールドは要求ペイロードに必ず含めます。フィールドは、以下の理由のいずれかにより必須となることがあります。

• そのフィールドは、関連スキーマで必須のマークが付いているため、そのスキーマを使用するすべての POST で含める必要がある。
• そのフィールドは、関連スキーマで必須のマークが付いていないが、ClaimCenter で常に必須となる（例：基になるデータベース列が、デフォルト値なしで Null 不可能のマークが付けられる可能性があり、アプリケーションがそれに対する値を生成しない）。
• そのフィールドは API では必須ではないが、ClaimCenter で必須の場合がある（例：機密以外のドキュメントでは作成者が必須ではないが、機密ドキュメントには必要という ClaimCenter の検証ルールがある可能性があるので、作成者フィールドが一部の場合にのみ必須となる）。

フィールドが POST で必須となるか、許可されるかどうかは、対応するデータモデルエンティティやデータベース列の必要性に必ずしも一致しません。例：

• フィールドは、データベースで Null 不可能のマークが付いている可能性があります（したがって「必須」）。しかし、ClaimCenter では、それに対して常に値を生成します。したがって、そのフィールドは読み取り専用のマークが付き、API スキーマでは必須となりません。
• フィールドは、オブジェクトが作成される際、データベースで Null 不可能のマークが付き（したがって「必須」）、必須である可能性があります。しかし、オブジェクトの作成後は、フィールドの値を変更できません。したがって、そのフィールドは作成には必須でも、更新では読み取り専用となります。

API でフィールドが必須であることの判別

API でフィールドが必須の場合、スキーマではフィールドの以下のプロパティを指定します。

"requiredForCreate": true

例えば、クレーム API には、特定のクレームの連絡先を作成する POST claim/{claimId}/contacts エンドポイントがあります。このエンドポイントが要求スキーマの定義に使用するデータエンベロープの 1 つが、ClaimContact スキーマです。これには以下が含まれます。

contactSubtype	string
                        x-gw-type: typekey.Contact
                        x-gw-extensions: OrderedMap { "createOnly": true,
                             "requiredForCreate": true }
dateOfBirth	   string($date)
                        x-gw-nullable: true
                        x-gw-extensions: OrderedMap { "before": "now",
                             "entitySubtype": "Person" }

contactSubtype フィールドには "requiredForCreate": true プロパティがあるのに対し、dateOfBirth フィールドにはないことに注意してください。これはつまり、API では連絡先の作成に連絡先のサブタイプが必須ですが、生年月日は不要だということです。

アプリケーションでフィールドが必須であることの判別

フィールドが API では必須ではないが、アプリケーションで必須の場合、これを識別する方法は、要求をアプリケーションに送信することのみです。必須の値が要求ペイロードから失われている場合、失われたフィールドを特定するメッセージと共に BadInputException の応答を取得します。例：

{
        "status": 400,
        "errorCode": "gw.api.rest.exceptions.BadInputException",
        "userMessage": "The 'body' field is required when creating notes"
        }

読み取り専用のフィールド

読み取り専用のフィールドは、（ユーザーまたはアプリケーションロジックのいずれかによって）アプリケーション内で設定されるフィールドで、システム API の呼び出しで設定または変更することができません。読み取り専用のフィールドは、要求スキーマの一覧に readonly: true と表示されます。この情報は、エンドポイントの［モデル］ タブを使用して Swagger UI で表示できます。

例えば、これは POST /activity/{activityId}/notes エンドポイントの createDate フィールドのモデルテキストです。

createdDate	  string($date-time)
                       readOnly: true

要求ペイロードには、読み取り専用の値を含めることはできません。含めた場合、API では以下のようなエラーメッセージと共に BadInputException を返します。

"message": "Property 'createdDate' is defined as read-only and cannot be specified on inputs"

オプションのフィールド

技術的な観点では、必須でも読み取り専用でもないフィールドはすべてオプションです。こうしたフィールドは、必要に応じて含めることも、省略することもできます。

ID

ID の値は ClaimCenter によってアサインされます。したがって、作成中のオブジェクトの ID は指定できません。ただし、新規オブジェクトに関連する既存オブジェクトを指定する際、ID を指定できます。

タイプキー

タイプキーは以下の形式を使用します。

"field": {
    "code": "value"
}

例：

"priority": {
    "code": "urgent"
}

タイプキーには name フィールドもあり、このフィールドは応答に含まれます。しかし、name フィールドは必須ではありません。要求スキーマに含めると、無視されます。

金額

金額には以下の形式を使用します。

"field": {
    "amount": "amountValue",
    "currency": "currencyCode"
}

例：

"transactionAmount": {
    "amount": "500.00",
    "currency": "usd"
}

（システム API で、このデータ型は MonetaryAmount と呼ばれますが、 ClaimCenter では、これらの値は実際には CurrencyAmount データ型を使用して保存されることに注意してください。）

関連オブジェクト

要求ペイロードで関連オブジェクトを指定する方法の詳細については、要求包含を参照してください。