Validieren Sie eine REST- API zur Verwendung mit Jitterbit Design Studio

Einführung

Auf dieser Seite zeigen wir, wie Sie mit einem unabhängigen Tool die Anforderungs- und Antwortstrukturen einer REST-API validieren. Diese Seite ist eine Fortsetzung des REST- API Tutorials mithilfe von Atlassian Jira Cloud REST API v2 als Beispiel, als Fortsetzung des vorherigen Schritts Erforschung einer REST- API. Diese exemplarische Vorgehensweise richtet sich an unerfahrene Benutzer, die mit API Tests und-Validierung nicht vertraut sind.

Bevor Sie mit Harmony eine Verbindung zu einer REST- API herstellen, wird aus mehreren Gründen dringend empfohlen, Tests und Validierungen mit einem unabhängigen Tool durchzuführen:

• Gezielte Fehlerbehebung: Die meisten Probleme mit REST- APIs in Harmony sind darauf zurückzuführen, dass die Anforderung nicht wie erforderlich erstellt wurde, um die gewünschte Antwort von der API abzurufen. Durch die Durchführung dieser Fehlerbehebung mit einem unabhängigen Tool wird sichergestellt, dass die spezifischen Anforderungen gültig sind, bevor die Automatisierung eingeführt wird.

• Schnelle Iteration: Beim Entwerfen einer Integration kennen Sie möglicherweise nicht alle gewünschten Felder oder Werte oder können beim ersten Versuch keine gültigen Anfragen stellen. Durch die Durchführung schneller Tests, die sofortiges Feedback liefern, können Sie die Anfragen für Ihren spezifischen Anwendungsfall auf effiziente Weise erstellen und Ihre Anfrage so lange ändern, bis die gewünschte Antwort generiert wird.

• Tatsächliche Strukturen: Die API Dokumentation für Beispielstrukturen für Anfragen und Antworten kann veraltet sein, eine für Ihren Endpoint spezifische Konfiguration nicht berücksichtigen, unvollständig oder auf andere Weise ungenau sein. Aus Erfahrung empfehlen wir dringend, die tatsächlichen strukturierten Datenantworten der API selbst zu verwenden, damit Harmony weiß, wie Ihre Daten richtig verarbeitet werden.

Für die Validierung von REST- APIs stehen zahlreiche Tools zur Verfügung. In diesem Tutorial verwenden wir den Postman wegen seiner Einfachheit, aber Sie können gerne jedes beliebige Tool Ihrer Wahl verwenden, wie zum Beispiel SoapUI. Falls verfügbar, können Sie auch das Entwickler eines API Anbieters oder die Testfunktionalität von OpenAPI/Swagger verwenden, solange die Anforderungs- und Antwortstrukturen bereitgestellt werden.

Testen der Authentifizierung

Der erste Testschritt besteht darin, sicherzustellen, dass Sie mit der konfigurierten Authentifizierungsart erfolgreich eine Verbindung zur REST- API herstellen können.

Suchen Sie in der API Dokumentation nach einer zu testenden Anforderungs URL, die eine Antwort liefert. Die Verwendung eines GET zum Testen der Authentifizierung ist häufig die einfachste Möglichkeit, um sicherzustellen, dass Sie eine Verbindung herstellen können. Andere Methoden, bei denen Daten an den Endpoint übertragen werden, erfordern möglicherweise Berechtigungen, die Sie später fehlerbehebung können, wenn Sie sicher sind, dass der Authentifizierungsteil funktioniert.

Erstellen Sie zunächst die Anforderungs URL und ersetzen Sie die Basis URL durch die URL für Ihren spezifischen Endpoint, sofern zutreffend. Machen Sie sich vorerst keine Gedanken über die Angabe der spezifischen Anforderungsdetails. Wir möchten nur sicherstellen, dass wir eine Verbindung herstellen können. Am Beispiel von Jiras „Get Create Issue Metadata“ finden wir in der Dokumentation, dass die Anforderungs URL wie folgt erstellt wird: https://<your-domain>.atlassian.net/rest/api/2/issue/createmeta. In Postman ist die Methode GET, wir verwenden das Dropdown-Menü, um GET auszuwählen und geben die Anforderungs URL für unseren Endpoint ein.

Geben Sie als Nächstes die Authentifizierungsdetails für Ihren Endpoint an. In Postman erfolgt dies im Abschnitt Authorization. Da wir eine Basisauthentifizierung verwenden, haben wir Basic Auth ausgewählt und die Jira-Anmeldeinformationen eingegeben, die wir später in Design Studio verwenden werden. Obwohl in diesem Beispiel eine Basisauthentifizierung verwendet wird, können Sie jeden von Ihrem Endpoint unterstützten Authentifizierungstyp verwenden.

Senden Sie die Anforderung mit der eingegebenen Anforderungs URL und den Authentifizierungsinformationen an die API (klicken Sie in Postman auf Senden). Wenn die Verbindung erfolgreich ist, sollten Sie eine Antwort von der API erhalten, in der Regel als Struktur, als erfolgreicher Statuscode oder beides, je nach spezifischer Methode und API. Wenn die Verbindung fehlschlägt, überprüfen Sie die API Dokumentation und Ihren Endpoint auf Konfigurationsfehler.

Validieren und Speichern von Strukturen für jede Anfrage und Antwort

Nachdem Sie bestätigt haben, dass Sie erfolgreich eine Verbindung mit der REST API herstellen können, verwenden Sie denselben Prozess, um (1) jede Anforderung zu validieren, die Harmony an die API stellen soll, um mit den Daten Ihres Endpunkts zu interagieren, und (2) die Anforderungs- und Antwortstrukturen (sofern vorhanden) in separaten Dateien zu speichern, die Sie später in Design Studio benötigen.

Um jede Anforderung in Postman zu validieren, befolgen Sie dieselben Schritte wie zuvor, um die Anforderungs URL (für jeden Aufruf) und die Authentifizierungsdetails anzugeben.

Wenn ein Aufruf eine Anforderungsstruktur erfordert, für die Sie zuvor ein Beispiel aus der API Dokumentation erhalten haben sollten, müssen Sie diese in Postman bereitstellen. Wählen Sie im Abschnitt Body das Optionsfeld raw aus und legen Sie über die Dropdownliste das entsprechende Format fest (content-type). Im Beispiel ist das Format wie bei den meisten REST- APIs JSON (application/json). Fügen Sie die Anforderungsstruktur ein und nehmen Sie bei Bedarf Anpassungen vor, damit die Anforderung gültig ist (z. B. Ändern des Jira-Projektschlüssels und des Problemtyps). Diese Anpassungen hängen von Ihrer tatsächlichen API Anforderung ab.

Wenn Sie die Anforderungsinformationen eingegeben haben, klicken Sie auf Senden. Führen Sie bei Bedarf eine fehlerbehebung und wiederholen Sie die Schritte, bis Sie die gewünschte API Antwortstruktur erhalten. Die tatsächlichen Daten in der Beispielantwort sind nicht relevant, da die REST- API die tatsächlichen Daten zum Zeitpunkt der Anforderung an Harmony übermittelt.

Nachdem Sie die Datenstruktur haben, die Sie in Ihrer Integration verwenden möchten, speichern Sie jede Anforderungs- und Antwortstruktur (sofern vorhanden) in einer eigenen Datei. Stellen Sie sicher, dass Sie im richtigen Dateiformat speichern. Die meisten REST- APIs liefern Antworten in JSON, manche verwenden jedoch je nach API XML oder einen anderen Typ. Speichern Sie die Dateien an einem Ort, an dem Sie darauf zugreifen können, wenn Sie Ihr Projekt in Design Studio einrichten.

Beachten Sie, dass es völlig in Ordnung und erwünscht ist, wenn Sie nicht beabsichtigen, alle in der Antwort angegebenen Felder in Ihrer Integration zu verwenden. Sie können sie einfach drin lassen oder sie bei Bedarf manuell aus der Beispielstruktur entfernen. Sie müssen jedoch sicherstellen, dass alle Felder, die Sie verwenden möchten, enthalten sind. Andernfalls können Sie sie in Harmony nicht verwenden.

Für dieses Beispiel haben wir Postman verwendet, um die folgenden Anforderungs- und Antwortstrukturen zu validieren, und diese Strukturen dann in lokalen Dateien gespeichert. Dies sind die Dateien, die wir später in Design Studio bereitstellen müssen, während wir die Transformation konfigurieren, damit Harmony die Daten korrekt verarbeiten kann.

Jira GET „Problem abrufen“

In diesem gängigen Szenario verwenden wir zunächst eine GET-Methode, die tatsächliche Felder und Werte von einem vorhandenen Objekt innerhalb des Endpoint zurückgibt. Nachdem wir gesehen haben, was diese Felder und Werte sind, können wir sie später in einer PUT-, POST-, DELETE- oder anderen Methode verwenden.

• Anforderungs URL: GET https://my-domain.atlassian.net/rest/api/2/issue/TEST-10

• Anforderungsstruktur: Keine. Die Jira API Dokumentation gibt an, dass der Anforderung keine Eingabedaten zugeordnet sind. Das ist sinnvoll, da das angeforderte Objekt in der Anforderungs URL angegeben ist.

• Antwortstruktur: Wir haben die Antwortstruktur bearbeitet, um Felder zu entfernen, die wir nicht verwenden möchten (ein optionaler Schritt), und sie in einer lokalen Datei namens Jira_GET_GetIssue_Response.json:

  Jira_GET_GetIssue_Response.json

  {
      "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
      "id": "10572",
      "self": "https://my-domain.atlassian.net/rest/api/2/issue/10572",
      "key": "TEST-10",
      "fields": {
          "issuetype": {
              "self": "https://my-domain.atlassian.net/rest/api/2/issuetype/10003",
              "id": "10003",
              "description": "A task that needs to be done.",
              "name": "Task",
              "subtask": false
          },
          "project": {
              "id": "10200",
              "key": "TEST"
          },
          "priority": {
              "self": "https://my-domain.atlassian.net/rest/api/2/priority/3",
              "iconUrl": "https://my-domain.atlassian.net/images/icons/priorities/medium.svg",
              "name": "Medium",
              "id": "3"
          },
          "labels": [],
          "versions": [],
          "status": {
              "name": "To Do"
          },
          "description": "This task is for manually updating JIRA because there is no integration in place.",
          "security": null,
          "summary": "Manual Updates",
          "comment": {
              "comments": [],
              "maxResults": 0,
              "total": 0,
              "startAt": 0
          }
      }
  }
  

Jira POST „Problem erstellen“

Wir senden nun eine Anfrage zum Erstellen eines neuen Objekts unter Verwendung einiger der gleichen Felder, die vom GET zurückgegeben wurden. Um die möglichen Werte zu erfahren, könnten Sie zunächst ein anderes GET aufrufen, das dieselbe Struktur zurückgibt.

• Anforderungs URL: POST https://my-domain.atlassian.net/rest/api/2/issue/

• Anforderungsstruktur: Gespeichert in einer lokalen Datei namens Jira_POST_CreateIssue_Request.json.

  Jira_POST_CreateIssue_Request.json

  {
      "fields": {
         "project":
         {
            "key": "TEST"
         },
         "summary": "Jitterbit REST API Integration",
         "description": "Build an integration in Jitterbit so we can automatically sync our systems using our endpoint's REST API.",
         "priority": {
          "name": "Medium"
          },
         "issuetype": {
            "name": "Task"
         }
     }
  }
  

• Antwortstruktur: Gespeichert in einer lokalen Datei namens Jira_POST_CreateIssue_Response.json. Wir können auch unseren Endpoint überprüfen, um zu sehen, dass das neue Problem erstellt wurde, oder ein GET für die Kennung des neuen Objekts ausführen.

  Jira_POST_CreateIssue_Response.json

  {
      "id": "10576",
      "key": "TEST-11",
      "self": "https://jitterbitse.atlassian.net/rest/api/2/issue/10576"
  }
  

Jira PUT „Problem bearbeiten“

Als Nächstes bearbeiten wir das gerade erstellte Problem, um die Werte einiger seiner vorhandenen Felder zu ändern und neue hinzuzufügen.

• Anforderungs URL: PUT https://my-domain.atlassian.net/rest/api/2/issue/TEST-11

• Anforderungsstruktur: Gespeichert in einer lokalen Datei namens Jira_PUT_EditIssue_Request.json.

  Jira_PUT_EditIssue_Request.json

  {
    "update": {
      "comment": [
        {
          "add": {
            "body": "Ticket updated via REST API."
          }
        }
      ]
    },
    "fields": {
      "priority": {
          "name": "Highest"
      },
      "labels": ["business-priority", "customer-priority"]
      }
  }
  

• Antwortstruktur: Keine. In Postman haben wir einen Statuscode 204 erhalten, der laut API Dokumentation die erwartete Antwort ist, wenn das Problem erfolgreich behoben wurde. Wir können auch unseren Endpoint in der Jira-Webanwendung überprüfen oder ein weiteres GET ausführen, um zu sehen, dass die Aktualisierungen vorgenommen wurden.

Jira DELETE „Problem löschen“

Abschließend löschen wir das Objekt, das wir erstellt und bearbeitet haben.

• Anforderungs URL: LÖSCHEN https://my-domain.atlassian.net/rest/api/2/issue/TEST-11

• Anforderungsstruktur: Keine. Die Objektkennung wird in der URL bereitgestellt.

• Antwortstruktur: Keine. Der zurückgegebene Statuscode ist 204, was laut Jira API Dokumentation bedeutet, dass das Problem erfolgreich behoben wurde. Dies kann auch in der Jira-Webanwendung überprüft oder mit einem erfolglosen GET bestätigt werden.

Nächste Schritte

Nachdem Sie die Struktur für jede Anfrage und Antwort validiert und gespeichert haben, finden Sie die nächsten Schritte auf diesen Seiten:

• Verbindung zu einer REST- API herstellen
  In Design Studio muss eine HTTP-Quelle oder ein HTTP-Ziel für die entsprechende HTTP-Methode Ihrer Anfrage (GET, PUT, POST, DELETE oder benutzerdefinierte Methode) konfiguriert werden, damit Sie sie in einer Operation verwenden können. Während sich diese Seite auf allgemeine Konfigurationsoptionen konzentriert, sind die Seiten HTTP-Quelle und HTTP-Ziel bieten ausführlichere Informationen zu allen Optionen, die konfiguriert werden können.

• Verwenden einer REST- API im Operation
  Obwohl jede REST- API den gleichen architektonischen Einschränkungen unterliegt, sind sie nicht alle für jede HTTP-Methode gleich konzipiert. Da jede spezifische Anfrage und Antwort von der spezifischen API abhängt, stellen wir vier Entwurfsmuster für den Entwurf von Vorgängen vor.