Entwerfen von Anforderungs-Nutzdaten

Pflichtfelder

Ein Pflichtfeld muss in den Anforderungs-Nutzdaten enthalten sein. Ein Feld kann aus verschiedenen Gründen erforderlich sein:

• Das Feld ist im zugehörigen Schema als erforderlich gekennzeichnet und muss daher in allen POSTs enthalten sein, die dieses Schema verwenden.
• Das Feld ist im zugehörigen Schema nicht als erforderlich gekennzeichnet, wird aber immer von ClaimCenter benötigt. (Beispielsweise kann die zugrunde liegende Datenbankspalte ohne Standard als nicht nullfähig markiert werden, und die Anwendung generiert keinen Wert dafür.)
• Das Feld wird von der API nicht benötigt, aber manchmal von ClaimCenter. (Beispielsweise könnte es in ClaimCenter eine Validierungsregel geben, die besagt, dass nicht vertrauliche Dokumente keinen Verfasser erfordern, vertrauliche Dokumente jedoch. Daher ist das Feld "author" nur für einen Teil der Zeit erforderlich.)

Ob ein Feld in einem POST erforderlich oder zulässig ist, entspricht nicht immer der Anforderung der entsprechenden Datenmodellentität oder Datenbankspalte. Zum Beispiel:

• Ein Feld kann in der Datenbank als nicht nullfähig markiert werden (und ist daher "erforderlich"). ClaimCenter erzeugt allerdings immer einen Wert dafür. Daher ist das Feld im API-Schema als schreibgeschützt gekennzeichnet und nicht erforderlich.
• Ein Feld kann in der Datenbank als nicht nullfähig (und daher als "erforderlich") markiert werden und ist erforderlich, wenn ein Objekt erstellt wird. Sobald das Objekt erstellt ist, kann der Wert des Felds jedoch nicht mehr geändert werden. Daher ist das Feld für die Erstellung erforderlich, für Aktualisierungen jedoch schreibgeschützt.

Ermitteln, ob ein Feld von der API benötigt wird

Wenn ein Feld von der API benötigt wird, gibt das Schema die folgende Eigenschaft für das Feld an:

"requiredForCreate": true

Beispielsweise verfügt die Schadenfall-API über einen Endpunkt POST claim/{claimId}/contacts, der einen Kontakt für einen bestimmten Schadenfall erstellt. Einer der von diesem Endpunkt zum Definieren des Anforderungsschemas verwendeten Daten-Envelopes ist das Schema ClaimContact. Dieses enthält Folgendes:

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" }

Beachten Sie, dass das Feld contactSubtype die Eigenschaft "requiredForCreate": true enthält, während das Feld dateOfBirth dies nicht tut. Das bedeutet, dass die API für die Kontakterstellung einen Kontaktuntertyp, jedoch kein Geburtsdatum erfordert.

Ermitteln, ob ein Feld von der Anwendung benötigt wird

Wenn ein Feld von der API nicht benötigt wird, aber von der Anwendung benötigt wird, besteht die einzige Möglichkeit, dies zu ermitteln, darin, eine Anforderung an die Anwendung zu senden. Wenn ein erforderlicher Wert in Anforderungs-Nutzdaten fehlt, erhalten Sie eine Antwort BadInputException mit einer Meldung, die die fehlenden Felder angibt. Zum Beispiel:

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

Schreibgeschützte Felder

Schreibgeschützte Felder sind Felder, die in der Anwendung (entweder von einem Benutzer oder von der Anwendungslogik) festgelegt werden und nicht durch System-API-Aufrufe festgelegt oder geändert werden können. Schreibgeschützte Felder sind im Anforderungsschema als readonly: true aufgeführt. Sie können diese Informationen in der Swagger-Benutzeroberfläche auf der Registerkarte Model des Endpunkts anzeigen.

Dies ist beispielsweise der Modelltext für das Feld createDate des Endpunkts /activity/{activityId}/notes:

createdDate	  string($date-time)
                       readOnly: true

Schreibgeschützten Werte können nicht in Anforderungs-Nutzdaten eingefügt werden. In diesem Fall gibt die API eine BadInputException zurück, mit einer Fehlermeldung wie:

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

Optionale Felder

Aus technischer Sicht ist jedes Feld, das weder erforderlich noch schreibgeschützt ist, optional. Diese Felder können entweder eingeschlossen oder weggelassen werden.

IDs

ID-Werte werden zugewiesen von ClaimCenter. Daher können Sie keine ID für ein erstelltes Objekt angeben. Sie können jedoch IDs angeben, wenn Sie ein vorhandenes Objekt identifizieren, mit dem das neue Objekt verbunden ist.

Typenschlüssel

Typenschlüssel verwenden das folgende Format:

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

Zum Beispiel:

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

Typenschlüssel haben auch ein Feld name, das in Antworten enthalten ist. Das Feld "name" ist jedoch nicht erforderlich. Wenn Sie es in ein Anforderungsschema aufnehmen, wird es ignoriert.

Geldbeträge

Geldbeträge verwenden das folgende Format:

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

Zum Beispiel:

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

(Beachten Sie, dass der Datentyp in den System-APIs als MonetaryAmount bezeichnet wird. In ClaimCenter werden diese Werte jedoch mit dem Datentyp CurrencyAmount gespeichert.)

Zugehörige Objekte

Informationen zum Angeben verwandter Objekte in Anforderungs-Nutzdaten finden Sie unter Anforderungseinschluss.