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 nutzen

Für OpenAPI-Spezifikationen unterstützt Deployment Manager zwei Verhaltensweisen, um eine RESTful-Schnittstelle zu identifizieren. Die erste gilt für den Fall, dass alle REST-Methoden einer Ressource zum selben Ressourcenpfad gehören:

/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 /foo-Ressource 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 Managers 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 POST- und PUT-Methoden. Dies gilt auch für die Parameterwerte. Das heißt, Sie sollten für alle Parameterwerte in allen Methoden dieselbe Syntax verwenden.

Wenn Sie zum Beispiel einen Parameter namens email für den Anfragetext einer POST-Anfrage verwenden, sollten Sie denselben Parameter nicht emailAddress für die PUT-Anfrage nennen.

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 sollte der Anfragetext für POST- und PUT-Methoden identisch sein. Für die Methoden "get" und "delete" genügt der Pfad, denn es wird davon ausgegangen, dass diese Methoden keinen Anfragetext haben.

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

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Cloud Deployment Manager-Dokumentation