Best Practices für das Hinzufügen eines Typanbieters

Auf dieser Seite werden Best Practices zum Erstellen einer neuen API beschrieben, die dem Deployment Manager oder einer vorhandenen API als Typanbieter hinzugefügt werden kann.

Mit Deployment Manager können Sie APIs als Typanbieter hinzufügen und so die API-Ressourcen als Typen anzeigen, die sich in deren Konfiguration aufrufen lassen. Um diesen Prozess für Sie zu vereinfachen, sollten Sie diese Best Practices beim Konfigurieren oder Erstellen einer API anwenden.

Neue API erstellen

Wenn Sie eine neue API erstellen und diese mit Deployment Manager integrieren möchten, verwenden Sie diese Best Practices.

Standardmethoden zum Erstellen, Lesen, Aktualisieren und Löschen (CRUD) verwenden und benutzerdefinierte Methoden vermeiden

Sie sollten möglichst keine benutzerdefinierten Methoden verwenden. Halten Sie sich an Standard-REST-Methoden wie GET, POST, PUT und DELETE. Diese Methoden werden von Deployment Manager erkannt und können automatisch zugeordnet werden.

Für Discovery-APIs sollten Sie Ihre API-Methoden gemäß der folgenden Zuordnung benennen:

REST-Methode Empfohlene API-Benennung
POST create oder insert
GET get
PUT update
DELETE delete

Für OpenAPI-Spezifikationen dürfen Sie Ihre API-Methoden nicht anders als die Standard-REST-Methoden benennen.

Vorhersehbare Ressourcenpfade verwenden

Für OpenAPI-Spezifikationen unterstützt Deployment Manager zwei Verhaltensweisen, um eine RESTful-Schnittstelle zu identifizieren. Bei der ersten Verhaltensweise gehören alle REST-Methoden für eine Ressource zum selben Ressourcenpfad:

/foo/{name}
  post:
  get:
  delete:
  put:

Wenn Sie diese Methoden aufteilen müssen, verwenden Sie denselben Ressourcenpfad. Der folgende Pfad ist beispielsweise gültig, da er sich auf dieselbe Ressource /foo bezieht:

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

Der folgende Pfad ist jedoch ungültig, da er sich aus der Sicht von Deployment Manager auf zwei verschiedene Ressourcen bezieht:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

In manchen Fällen könnten Sie versuchen, Ihre Ressourcenpfade wie folgt zu benennen:

foo/create
  post:

foo/delete
  delete:

Dies ist aus der Sicht von Deployment Manager ungültig, da die RESTful-Schnittstelle nicht identifiziert werden kann.

Konsistente Benennungen innerhalb der Benutzeroberfläche verwenden

Verwenden Sie die gleichen Eingabe- und Pfadnamen für die Methoden POST und PUT. Dies gilt auch für die Parameterwerte. Das heißt, Sie sollten für alle Parameterwerte in allen Methoden dieselbe Syntax verwenden.

Wenn Sie beispielsweise einen Parameter mit dem Namen email für den Anfragetext einer POST-Anfrage haben, nennen Sie den entsprechenden Parameter für die PUT-Anfrage nicht emailAddress.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

Wenn Sie diese Art von Verhalten hinzufügen müssen, weisen Sie Deployment Manager an, wie dieses Verhalten behandelt werden soll, indem Sie erweiterte API-Optionen festlegen.

Darüber hinaus muss der Anfragetext für die Methoden POST und PUT identisch sein. Für die Methoden GET und DELETE gilt nur der Pfad, da für diese Methoden kein Anfragetext vorhanden ist.

Vorhandene API integrieren

Je nach Art der API kann die Integration einer vorhandenen API einen sehr unterschiedlichen Prozess erfordern. Deshalb gibt es keine konkreten Empfehlungen und Best Practices, die für alle APIs gelten. Nachstehend finden Sie eine Liste mit allgemeinen Tipps, die hilfreich sein können, wenn Sie eine bestehende API integrieren möchten.

  • Verwenden Sie einen API-Wrapper für Nicht-RESTful APIs.

    Wenn eine vorhandene API keine RESTful API ist, können Sie einen API-Wrapper erstellen, um nur die REST-Methoden verfügbar zu machen.

  • Wenn die API fast RESTful ist, identifizieren und aktualisieren Sie die API.

    Wenn Ihre API fast RESTful ist und nur wenig Nicht-REST-Verhalten aufweist, können Sie die API aktualisieren und so Probleme durch diese Verhaltensweisen lösen.

  • Servergenerierte Werte erfordern immer eine Eingabezuordnung.

    Wenn Ihre API servergenerierte Werte vorsieht, die von API-Methoden benötigt werden, müssen Sie Eingabezuordnungen einrichten, um die servergenerierten Werte abzurufen und diese bei jeder Anfrage zuzuordnen.

Weitere Informationen