Konzept: REST-API für Adaptive Planning
Der grundlegende REST-API-Ansatz
Die Adaptive Planning API umfasst drei allgemeine Bereiche:
- Abrufen und Bearbeiten von Metadaten.
- Datenabruf.
- Datenerstellung und -aktualisierung
Ein Client ruft einen API-Aufruf auf, indem er eine HTTP-Anforderung POST an den Hauptendpunkt der Adaptive Planning-Webservices sendet. Der Endpunkt enthält eine Versionsnummer, die die verwendete API-Version angibt. Die aktuelle Version der Adaptive Planning API ist v40. Wenn Ihre Instanz eine nicht auf den USA basierende regionale Authentifizierung verwendet, variieren Ihre Autorisierungs-URLs und API-Endpunkte je nach Region. Siehe: Referenz: Regionale Authentifizierungs-URLs.
https://api.adaptiveplanning.com/api/v40
API-Versionen werden in der Regel mit neuen Produkt-Releases von Adaptive Planning aktualisiert, wobei jedoch nicht alle Produkt-Releases in einer neuen API-Version resultieren. Workday unterstützt die aktuelle Version mindestens ein Jahr nach dem Release der nachfolgenden API-Version.
Eine Historie der API-Änderungen finden Sie unter API-Änderungen nach Release.
Die HTTP-Anforderung POST enthält Posting-Daten in einem XML-Dokument. Dieses XML-Dokument enthält Standardabschnitte, die in jedem API-Methodenaufruf vorhanden sind, und Abschnitte, die für jeden API-Methodenaufruf spezifisch sind. Der Adaptive Planning-Server verarbeitet den API-Methodenaufruf und gibt die Ergebnisse als weiteres XML-Dokument zurück. Wie die Anforderung enthält das XML-Antwortdokument Abschnitte, die für jede API-Methode identisch sind, und Abschnitte, die für jede API-Methode spezifisch sind.
Jeder Datenabruf verwendet eine Suche. Der Aufrufer gibt Kriterien an, die mit einer Reihe von Elementen übereinstimmen, und der Server antwortet mit einer Liste von Metadatenentitäten oder Daten, die den Kriterien entsprechen. Bei der Datenerstellung und -aktualisierung erfolgt ein Massen-Upload von Daten, die ebenfalls über eine POST-Anweisung übermittelt werden.
Sicherheit
Der Benutzer muss bei jedem separaten Aufruf authentifiziert werden, wodurch die Möglichkeit ausgeschlossen wird, dass ein Eindringling eine Webservice-Sitzung kapert.
Alle API-Anforderungen sind verschlüsselt, da sie das HTTPS-Webprotokoll verwenden müssen. Die Authentifizierungsdaten des Benutzers werden als Teil des Webservice-Anforderungstexts an Adaptive Planning übermittelt. Dies bedeutet, dass die Webschicht die Anmelde-ID und das Kennwort eines Benutzers verschlüsselt, bevor dieser den Computer verlässt, der die Webservice-Anforderung generiert, und nur dann entschlüsselt, wenn der Zielserver sie erhält.
Die Authentifizierung eines Benutzers in einer API-Anforderung erstellt keine persistente Sitzung für diesen Benutzer. jeder separate Webservice-Aufruf muss seinen Benutzer separat authentifizieren.
Berechtigungen und Datenzugriffssteuerung
Ein Benutzer benötigt keine spezielle Berechtigung für den Zugriff auf Webservices. Der Benutzer, der die Webservice-Anforderung stellt, muss jedoch über die erforderlichen Berechtigungen verfügen, um die angeforderte Aktion auszuführen. Beispiel: Ein Benutzer muss über die Berechtigung „Importmöglichkeiten“
verfügen, um die Webservicemethode importStandardData aufzurufen.
Darüber hinaus beschränken die Webservice-Methoden die Ausgabe jedes Aufrufs auf das Dataset, das für den anfordernden Benutzer sichtbar ist. Beispiel: Die Webservicemethode exportData beschränkt die zurückgegebenen Daten auf die Daten, die in den Ebenen gefunden wurden, deren Eigentümer der aufrufende Benutzer ist.