Endpunkte

Jeder Endpunkt verfügt über eine Stammressource. Die Stammressource ist die Ressource, die der Endpunkt erstellt, aktualisiert, löscht oder abfragt. Bei jedem Aufruf eines Endpunkts wird die Stammressource verwendet.

Die Stammressource für den Endpunkt /common/v1/activities ist beispielsweise Activity. Dieser Endpunkt wird zum Erstellen, Aktualisieren, Löschen oder Abfragen von Aktivitäten verwendet.

Die meisten Endpunkte enthalten auch untergeordnete Ressourcen. Eine untergeordnete Ressource ist eine mit der Stammressource verbundene Ressource. Untergeordnete Ressourcen verbessern die Verwendbarkeit eines Endpunkts, indem sie Zugriff auf Informationen bieten, die sich auf die Stammressource beziehen. Beispiel: Der Endpunkt /common/v1/activities hat eine untergeordnete Ressource: Notes. Dies bedeutet, dass Sie den Endpunkt für Folgendes verwenden können:

• Abfrage nach einer bestimmten Aktivität (und nur nach der Aktivität)
• Abfrage nach einer bestimmten Aktivität und der zugehörigen Notizen

Bei jedem Aufruf eines Endpunkts muss die Stammressource verwendet werden. Die Verwendung von untergeordneten Ressourcen ist optional.

Inline- und eingeschlossene Ressourcen

Untergeordnete Ressourcen können entweder als Inline-Ressourcen oder als eingeschlossene Ressourcen deklariert werden.

• Eine Inline-Ressource ist eine Ressource, die im Abschnitt attributes der Nutzdaten inline mit den anderen Stammressourcenfeldern angezeigt wird, z. B. das Feld assignedUser einer Activity-Ressource. Diese Ressourcen können standardmäßig in einer Antwort enthalten sein und über die fields-Abfrageparameter gesteuert werden.
• Eine eingeschlossene Ressource ist eine Ressource, die im included-Abschnitt am unteren Ende der Nutzdaten erscheint, z. B. die Notes einer Activity-Ressource. Diese Ressourcen sind standardmäßig nicht in einer Antwort enthalten und müssen über die included-Abfrageparameter gesteuert werden.

Weitere Informationen zu Inline- und eingeschlossenen Ressourcen finden Sie unter GETs und Antwort-Nutzdatenstrukturen.

Eine Operation ist ein Aktionstyp, den eine aufrufende Anwendung über einen Endpunkt auf eine Ressource anwenden kann. Operationen werden auch als Verben oder Methoden bezeichnet. Die System-APIs unterstützen die folgenden Teilmengen von HTTP-Operationen:

• GET: Wird zum Anfordern von Ressourcen verwendet.
• POST: Wird zum Erstellen von Ressourcen verwendet. Wird auch zur Ausführung von Geschäftsaktionen wie der Angebotserstellung für einen Antrag oder dem Übermitteln eines Schadenfalls verwendet.
• PATCH: Wird zum Aktualisieren von Ressourcen verwendet.
• DELETE: Wird zum Löschen von Ressourcen verwendet.

Jeder Endpunkt unterstützt eine oder mehrere dieser Operationen. Beispielsweise gilt für die Common-API:

• Der notes/{noteId}-Endpunkt unterstützt GET, PATCH und DELETE.
• Der /activities-Endpunkt unterstützt nur die GET-Operation.

Die HTTP-Operationen sind für CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen) vorgesehen. Einige Geschäftsprozesse in InsuranceSuite-Anwendungen sind für die System-APIs verfügbar, werden jedoch nicht ohne Weiteres diesen Operationen zugeordnet, z. B. das Zuweisen von Objekten, das Schließen von Objekten oder das Genehmigen von Objekten. In der Regel verwenden die benutzerdefinierten Aktionen, die diese Prozesse auslösen, die POST-Operation.

Zuordnung von Operationen zu Elementen und Sammlungen

Im Allgemeinen gilt:

• Sie verwenden GET, um entweder ein Element oder eine Sammlung abzurufen.
• Sie verwenden POST für eine Sammlung, um ein Element zu erstellen.
• Sie verwenden POST für eine benutzerdefinierte Aktion (um eine Geschäftsaktion auszuführen).
• Sie verwenden PATCH für ein Element.
• Sie verwenden DELETE für ein Element.

Zum Beispiel:

Operation	Am Endpunkt...	Bewirkt Folgendes...
GET	/activities	Gibt alle dem aktuellen Benutzer zugewiesenen Aktivitäten zurück
GET	/activities/{activityId}	Gibt die Details für die angegebene Aktivität zurück
POST	/activities/{activityId}/notes	Fügt der angegebenen Aktivität eine neue Notiz hinzu
POST	/activities/{activityId}/assign	Weist die Aktivität zu
PATCH	/activities/{activityId}	Aktualisiert Informationen über die angegebene Aktivität
DELETE	/notes/{NoteId}	Löscht die angegebene Notiz

Kontrastierende Endpunkte und Operationen

Technisch gesehen ist ein Endpunkt, wenn er mehrere Operationen unterstützt, immer noch ein einzelner Endpunkt. In der Umgangssprache wird jedoch jede Operation manchmal als separater Endpunkt bezeichnet. Betrachten wir beispielsweise das folgende Szenario:

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

Dies ist ein einzelner Endpunkt (/common/v1/activities), der zwei Operationen (GET und POST) unterstützt. Im umgangssprachlichen Sinne wird er jedoch manchmal als zwei Endpunkte bezeichnet (als der GET /activities-Endpunkt und der POST /activities-Endpunkt).

Die PUT-Operation

Innerhalb der REST-API-Architektur gibt es zwei Operationen, die vorhandene Ressourcen ändern: PATCH und PUT. PATCH wird verwendet, um einen Teil einer vorhandenen Ressource zu ändern (während andere Aspekte davon unverändert bleiben). PUT wird verwendet, um den gesamten Inhalt einer vorhandenen Ressource durch neue Daten zu ersetzen. Die System-APIs unterstützen die PATCH-Operation, nicht jedoch die PUT-Operation. Dies liegt daran, dass nahezu jede Operation, die ein InsuranceSuite-Objekt ändert, nur einen Teil davon ändert, während der Rest des Objekts unverändert bleibt. Dieses Verhalten wird PATCH zugeordnet, nicht jedoch PUT.

Jeder Endpunkt weist einen Pfad auf. Der Pfad ist der Teil der URL, der von aufrufenden Anwendungen zur Identifizierung des spezifischen Endpunkts verwendet wird.

Für die Cloud-API besteht jeder Pfad aus dem folgenden Muster:

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

Betrachten wir beispielsweise den Pfad: rest/common/v1/activities:

• common ist der Name der API, zu welcher der Endpunkt gehört.
• v1 ist die Hauptversionsnummer der API
• activities ist der Endpunktname

Die Hauptversionsnummer liefert Informationen über die Abwärtskompatibilität des Endpunkts. Weitere Informationen finden Sie unter Cloud-API-Versionen.

Ein Pfad kann auch einen Verweis auf eine bestimmte Ressource enthalten. Beispiel: Der Pfad /activities/xc:20/notes verweist auf die Notizen für die Aktivität xc:20. Wenn ein Pfad einen Verweis auf eine bestimmte Ressource enthält, wird der generische Pfadname mit {typeId} angegeben, wobei type der Ressourcentyp ist. Beispiel: Der generische Pfad für /activities/xc:20/notes lautet /activities/{activityID}/notes. Ein Verweis auf eine bestimmte Ressource in einem Pfad wird als Pfadparameter bezeichnet.

Bei den meisten Endpunkten ist der Endpunktname identisch mit dem Ressourcennamen, aber es gelten die folgenden Konventionen und Einschränkungen:

• Wenn die Stammressource des Endpunkts ein Element ist, endet der Endpunktname mit einem Substantiv im Singular (z. B. /activity) oder einem Ressourcenverweis (z. B. /activity/{activityId}).
• Wenn es sich bei der Stammressource des Endpunkts um eine Auflistung handelt, endet der Endpunktname mit einem Substantiv im Plural (z. B. /activities).
• Wenn der Endpunkt eine Geschäftsaktion ausführt, endet der Endpunktname mit einem Verb (z. B. /{activityId}/assign).
• Der Endpunktname befindet sich häufig in der Nähe des Ressourcennamen, ist jedoch nicht identisch mit diesem.
  • Endpunktnamen verwenden Kleinbuchstaben, während Ressourcennamen gemischte Groß-/Kleinschreibung verwenden (z. B. ist die Stammressource für den /activity-Endpunkt Activity)
  • Endpunktnamen verwenden Bindestriche, um Wörter zu trennen, Ressourcennamen hingegen nicht (z. B. ist die Stammressource für den /fixed-property-incidents-Endpunkt FixedPropertyIncident).
  • In einigen Fällen kann der Endpunktname vom Stammressourcennamen abweichen (z. B. ist die Stammressource für den /contacts-Endpunkt ClaimContact).