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

Einführung

Diese Seite richtet sich an diejenigen, die mit dem Vorgang des Sammelns von Informationen zu einer bestimmten API nicht vertraut sind, und behandelt die Einzelheiten, auf die in der Dokumentation einer API zu achten ist und die für die Einrichtung einer Integration in Harmony relevant sind.

Wenn Sie mit einer bestimmten API nicht vertraut sind, sollten Sie zunächst die zugehörige Dokumentation suchen. Einige APIs haben mehrere Versionen oder Produkte, achten Sie also auf die spezifische Version. Es wird immer üblicher, dass API Dokumentation in die API Implementierung eingebettet wird. Solche APIs können mithilfe der OpenAPI/Swagger-Spezifikation oder anderer Frameworks dokumentiert werden. Andere API Dokumentationen, die nicht eingebettet sind, können anfälliger für Ungenauigkeiten sein, was Tests und Validierungen noch wichtiger macht.

Für dieses Tutorial verwenden wir Atlassian Jira Cloud REST API v2 als Beispiel.

Authentifizierung

Suchen Sie in der API Dokumentation nach Anweisungen zum Konfigurieren des Authentifizierungstyps, den Harmony zur Authentifizierung mit der API verwenden soll, z. B. Basic, OAuth oder Token-basiert. Richten Sie dann die gewünschte Authentifizierung nach Bedarf ein.

Anhand des Jira Beispiels richten wir die Basisauthentifizierung gemäß der Jira-Dokumentation zu Basisauthentifizierung für REST-APIs ein mit dieser Art der Authentifizierung können wir Harmony so konfigurieren, dass zur Authentifizierung bei Jira ein Benutzername und ein Passwort verwendet werden.

Später in diesem Tutorial zeigen wir, wie Sie diese Konfiguration testen können (siehe Validieren einer REST API) und wie Sie die von Ihnen konfigurierte Authentifizierungsmethode verwenden, um eine HTTP-Quelle oder ein HTTP-Ziel in Design Studio zu konfigurieren (siehe Herstellen einer Verbindung zu einer REST- API).

Anforderungs URL

Für jeden Aufruf der API müssen Sie die zugehörige URL kennen. Die Dokumentation sollte zeigen, wie diese URL erstellt wird. Dabei handelt es sich häufig um eine Kombination aus einer Basis URL für den jeweiligen Endpoint und Parametern für die jeweilige Anfrage. Die URL kann Parameter enthalten, die durch die spezifischen Datensatzkennungen ersetzt werden sollen, mit denen Sie interagieren möchten.

In der API Dokumentation kann die URL oder Teil URL für jeden Anfragetyp aufgeführt oder innerhalb einer vollständigen Anfrage angezeigt werden. Die Jira-Dokumentation bietet beides. Beispielsweise wird der Teil-URL Pfad für „Problem erstellen“ bereitgestellt:

POST /rest/api/2/issue

Die Jira-Dokumentation enthält außerdem Beispiele für jede Anfrage für verschiedene Tools und Sprachen (wie cURL, Node.js, Java, Python und PHP). Die vollständige URL mit einem Dummy-Domänennamen, der ersetzt werden muss, finden Sie in jedem Beispiel. Die Beispiel-cURL-Anfrage liefert die URL nach dem --url Option:

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue'

In der Dokumentation einer API sollten alle Abfrage aufgeführt sein, die am Ende der URL hinzugefügt werden können. Später können Sie in Design Studio die Basis URL und alle Abfrage dynamisch gestalten, indem Sie diese durch Projekt- oder globale Variablen in der URL ersetzen, die in der HTTP-Quell- oder Zielkonfiguration angegeben ist. Ein Beispiel hierfür finden Sie später in diesem Tutorial unter Herstellen einer Verbindung zu einer REST- API.

Anforderungsheader

Notieren Sie sich bei jedem Aufruf einer REST- API alle in der Anfrage enthaltenen Header.

In Design Studio werden die am häufigsten enthaltenen Header-Informationen während der Standardkonfiguration einer HTTP-Quelle oder eines HTTP-Ziels angegeben, z. B. Authentifizierung und Inhaltstyp. Wenn Sie sich die erforderlichen Werte notieren, können Sie die Quelle oder das Ziel richtig konfigurieren. Zusätzliche Anforderungsheader können während der Konfiguration der Quelle/des Ziels unter Optionen > Erweiterte Eigenschaften angegeben werden (und werden in Herstellen einer Verbindung zu einer REST- API behandelt)).

In der Beispiel-cURL-Anforderung werden Header Informationen wie folgt bereitgestellt: --header Optionen:

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

Anforderungs- und Antwortstrukturen

Für jeden Aufruf einer REST- API müssen Sie die Anforderungs- und Antwortstrukturen kennen, sofern diese vorhanden sind.

Nicht alle API Aufrufe haben eine Anforderungs- oder Antwortstruktur. Ob ein Aufruf eine (oder beide) dieser Strukturen verwendet, hängt von der jeweiligen API ab. Gut dokumentierte APIs stellen normalerweise die Anforderungsstruktur bereit. Die Antwortstruktur kann bereitgestellt werden, kann aber in jedem Fall mit einem Tool wie Postman abgerufen werden oder SoapUI.

Bei Aufrufen, die strukturierte Anforderungsdaten akzeptieren, sollte die Struktur in der Dokumentation bereitgestellt werden, entweder in der Anforderung enthalten oder separat bereitgestellt. Codierte Anforderungen können für verschiedene Tools oder Sprachen gelten, wobei die Payload in einem von der API erwarteten Format vorliegt. Sie müssen also mit dem verwendeten Tool oder der verwendeten Sprache vertraut sein, um zu wissen, wo Sie nach der Anforderungsstruktur suchen müssen.

Beispielsweise ist in der Jira API Dokumentation für „Create Issue“ die Anforderungsstruktur enthalten in --data Option für cURL (siehe unten) und wird in mehreren anderen Sprachen bereitgestellt. Möglicherweise müssen Sie die Eingabedaten für die jeweilige Anfrage anpassen, indem Sie beispielsweise die Werte für alle Felder (wie den Jira-Projektschlüssel und den Problemtyp) durch diejenigen ersetzen, die für den jeweiligen Endpoint gültig sind. Sie müssen diese Eingabestruktur dann angeben, wenn Sie den Aufruf in einem Tool wie Postman validieren, wie später in Validieren einer REST- API beschrieben.

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"fields": {"project": {"key": "TEST"}, "summary": "REST ye merry gentlemen.", "description": "Creating of an issue using project keys and issue type names using the REST API", "issuetype": {"name": "Bug"}}}'

Some API calls do not contain any structured input data for the request. For example, in the case of Jira's "Get Issue," the absence of --Daten containing a structure indicates this call does not accept structured request data, as is common for GET calls.

``` Titel = ' Jira „Problem abrufen“ cURL-Anfrage' curl --Anfrage GET \ --url ' https:// .atlassian.net/rest/api/2/issue/' \ -- Header „Autorisierung: Inhaber “ \ -- Header „Akzeptieren: application/json“

```

Using a GET can be helpful in cases where the API documentation may not have an accurate or complete request structure, or in cases where you have added custom fields. You can perform a GET on an existing object to obtain a list of possible fields or values, then use that structure later in Postman to test what might be accepted for the request in another method.

For calls that return structured response data from the API, if the documentation provides a sample response, note what format it is in and familiarize yourself with what is returned. Most REST APIs provide responses in JSON, but some APIs may provide XML or another type. For now, you don't need to copy the response provided by the documentation; we will generate the actual response from the API later for use in Design Studio (see Validating a REST API).

Take note of any documented status codes that are expected to be returned. These will be useful as reference to interpret the response received from the API after making the request. For example, the following table shows codes that can be returned from the Jira "Create Issue" request. In addition to a status code, error messages with helpful information may be returned in a structured response.

Jira "Get Issue" Status Codes

Weitere für den Endpoint eindeutige Informationen

Es kann nicht genug betont werden, wie wichtig es ist, sich mit Ihrem Endpoint vertraut zu machen. Die Dokumentation einer API kann Empfehlungen oder Hinweise enthalten, die Ihnen dabei helfen. In der Jira Dokumentation gibt es beispielsweise spezielle Hinweise zu Berechtigungen, Ressourcenerweiterung, Paginierung und speziellen Headern. Wenn Sie wissen, was verfügbar (oder nicht verfügbar) ist, können Sie erfolgreiche Integrationen entwerfen und alle auftretenden Herausforderungen bewältigen.

Nächste Schritte

Nachdem Sie die gewünschte Authentifizierung eingerichtet und sich mit der API-Dokumentation vertraut gemacht haben, finden Sie auf diesen Seiten die nächsten Schritte:

• Validieren einer REST- API
  Bevor Sie mit Harmony eine Verbindung zu einer REST- API herstellen, wird dringend empfohlen, Tests und Validierungen mit einem unabhängigen Tool durchzuführen. Auf dieser Seite werden die Tests der Authentifizierung sowie das Validieren und Speichern von Strukturen für jede Anfrage und Antwort Schritt für Schritt beschrieben.

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