Definieren einer API-Spezifikation für einen externen Service

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:

Erläutern des Zwecks der API-Spezifikation
Erklären der Elemente einer von Externe Services unterstützten Schemadefinition
Nennen von drei Problemen, die dazu führen können, dass Ihre API-Spezifikation fehlschlägt

Gründe für eine Schemadefinition

In der vorhergehenden Einheit haben Sie gelernt, dass eine API-Spezifikation eine Datei mit dem beschreibenden Schema ist, das definiert, was eine API tun kann. Unabhängig davon, ob Sie am Ende derjenige sind, der eine API-Spezifikation für Ihre Registrierung bei Externe Services erstellt, ist es hilfreich zu wissen, was ihr Zweck ist und wie sie genutzt wird.

Nehmen wir einmal an, Sie haben eine auf REST basierende Bank-API. Sie benötigen ein allgemeines, standardisiertes Format, um die Struktur der REST-basierten API unserer Bank zu beschreiben. Geben Sie die API-Spezifikation ein. Salesforce nutzt als Beschreibungsformat die weit verbreitete OpenAPI-Spezifikation.

Ihre API-Spezifikation enthält eine Schemadefinition, in der beschrieben ist, welche Ein- und Ausgabetypen Sie in Aufrufe oder Anforderungen einbinden können, die Ihre Organisation an den externen Webservice richtet. Ihre Aufrufe können beispielsweise eine ID als numerische Eingabe oder einen name (Namen) als Textausgabe enthalten.

Darüber hinaus enthält die API-Spezifikation die Endpunktdaten und Authentifizierungsparameter für die REST-basierten API-Webservices, auf die Sie zugreifen können. (Zur Erinnerung: Am Endpunkt werden die Ressourcen der Webservices offengelegt, mit denen Externe Services interagiert.) Diese API-Spezifikation eines fiktiven Bank-Webservice enthält beispielsweise Methoden für das Hinzufügen und Löschen von Bankkonten. https://th-external-services.herokuapp.com/accounts/schema

In einer realen Anwendung müssten Sie gemäß den bewährten Methoden für Sicherheit einen Authentifizierungsschritt vor dem Zugriff auf die API einer Bank.

Da es sich bei Ihrer API-Spezifikation der fiktiven Bank um menschenlesbare, strukturierte Daten handelt, sehen wir uns diese genauer an.

Hier sind die grundlegenden Accountvorgänge in Ihrem Schema.

Vorgänge für Pfad: /accounts/{accountName}	Aufgabe
GET	Ruft einen Account ab
POST	Fügt einen Account hinzu
PUT	Aktualisiert einen Account
DELETE	Löscht einen Account

Der folgende Teil-Codeausschnitt aus dem Schema der API-Spezifikation enthält Informationen zu einer GET-Methode. Falls Sie sich damit nicht auskennen: Eine GET-Methode ruft einfach Ressourceninformationen aus einem Webservice ab. Im Falle der hier vorliegenden GET-Methode werden Informationen über ein Konto über den Ressourcenpfad abgerufen, in diesem Fall /accounts/{accountName}, wobei {accountName} ein bestimmtes Konto ist. Unter parameters sehen Sie "name":"accountName". Dieser Parameter muss mit dem angegebenen Accountnamen übereinstimmen und ist erforderlich ("required":true). Außerdem sollte er die Form einer Zeichenfolge aufweisen.

"paths": {
	"/accounts/{accountName}": 
	{ "get": 
		{ "operationId": "getAccount", 
		"summary": "Retrieves an account", 
		"description": "Retrieves the account with specific name",
		"consumes": ["text/plain"], 
		"produces": ["application/json"], 
		"parameters": [{ 
		"name": "accountName", 
		"in": "path", 
		"required": true, 
		"type": "string", 
		"description": "Name of the account" }], 
		"responses": { 
			"200": { 
				"description": "The response when system finds an account with given name", 
				"schema": { 
				"$ref": "#/definitions/accountDetails" } }, "400": 
				{ "description": "Error response if the account name parameter is less than minimum characters",
			"schema": 
			{ "$ref": "#/definitions/errorModel" } }, 
			"404": { 
			"description": "Error response if the account is not supported by service or account is not found",
			"schema": { "
			$ref": "#/definitions/errorModel" 
			}

Dies ist lediglich ein Teil einer viel umfassenderen Schemadefinition. Auf jeden Fall ist zu erkennen, dass es zwar für die Nutzung durch Externe Services konzipiert wurde, gleichzeitig jedoch von Menschen lesbar ist. Es ist zudem so logisch formatiert, dass Externe Services die Operationen verarbeiten kann, sodass sie als aufrufbare Aktionen in Tools wie dem Flow Builder oder Einstein Bots auftauchen können.

In den nächsten Schritten zeigen wir Ihnen, wie Sie die API-Spezifikation deklarativ registrieren. Zunächst beschäftigen wir uns jedoch mit den Elementen, die eine gültige und unterstützte Schemadefinition ausmachen, den detaillierten Beschreibungen jeder separaten API-Funktion, die in dem API-Spezifikationsdokument enthalten ist.

Was macht ein gültiges und unterstütztes Schema aus?

Jetzt wissen wir also, worum es bei einer API-Spezifikation geht. Doch was meinen wir mit einem gültigen und unterstützten Schema?

Es gibt Anforderungen an die Schemavalidierung, die in der OpenAPI-Spezifikation definiert sind, und es bestehen außerdem spezifische Schemaanforderungen für Externe Services. Externe Services kann Ihr Schema ordnungsgemäß unterstützen und Ihren Webservice aufrufen, wenn diese beiden Anforderungen erfüllt sind.

Einführung in die Schemavalidierung

Ein Schema muss nicht nur von Menschen, sondern auch von Computern gelesen werden können. Es muss einer logischen Struktur folgen, damit Externe Services es problemlos nutzen kann. Ein falsch strukturiertes Schema bedeutet, dass der externe Webservice nicht kommunizieren kann (Fehler- und Ausnahmemeldungen zurückgibt) und dass Externe Services ihn letztlich nicht einbinden kann. Die Beachtung struktureller, logischer und syntaktischer Einschränkungen ist ein notwendiger erster Schritt bei der Schemavalidierung. Die OpenAPI-Spezifikation definiert diese allgemeinen Regeln und macht das Herumprobieren beim Aufrufen eines externen Webservice überflüssig.

Unterstütztes Externe Services-Schema

Zusätzlich zu den allgemeinen OpenAPI-Richtlinien für die Schemavalidierung gibt es auch Schemaeinschränkungen, die speziell für Externe Services gelten. Sie sollten diese Anforderungen prüfen, ehe Sie Ihre API-Spezifikation bei Externe Services registrieren. Ein unterstütztes Schema in Externe Services bedeutet, dass Ihr Schema gemäß OpenAPI-Spezifikation gültig ist und zudem die spezifischen Anforderungen an Externe Services erfüllt. Beispielsweise kann der Registrierungsprozess einer API-Spezifikation fehlschlagen, wenn sie die Beschränkungen hinsichtlich der Dateigröße oder der Gesamtzahl an Objekten oder Aktionen überschreitet.

Eine Liste mit Schlüsselanforderungen für das Erstellen eines unterstützten Schemas für Externe Services finden Sie in der Salesforce-Hilfe: Überlegungen zu externen Services.