Page Comparison

https://yourdomain.com/api/v2/

• Die API Credentials können als “read-only” oder “read-and-write” eingerichtet werden.

• Es ist darauf zu achten, dass bei einem “read-and-write” Modus Livedaten beeinflusst - geändert/gelöscht - werden können.

• Kund:innen müssen sich also im Klaren darüber sein, wem sie diese Credentials weitergeben.

Bilder müssen für einen Import in das PORTAL von einer öffentlich zugänglichen URL abrufbar sein. Die Bilder können nicht direkt in das PORTAL eingespeist werden. Dies ist eine Maßnahme zur besseren Skalierbarkeit, um das System, bzw. die Schnittstelle nicht zu überlasten und eine schnelle Verarbeitung der Importe zu gewährleisten.

1. Einrichtung der API-Zugänge / Autorisierungsdaten

Rufen Sie die Verwaltung für API-Zugänge auf und erstellen Sie die benötigten API-Zugänge. Eine detaillierte Anleitung finden Sie hier: https://peiq.atlassian.net/wiki/spaces/PUPKB/pages/249168027#API-Zugang-erstellen

Nachdem Sie die Zugänge erfolgreich erstellt haben, erhalten Sie dort pro Zugang die API-Credentials: Client ID und Client Secret

2. Zugang zur API Dokumentation 2.0 BETA

Die interaktive Entwickler-Dokumentation der PEIQ Cloud-Connect APIs kann in jedem PORTAL über die Administrations & Moderation > Sonstige > API 2.0 BETA Dokumentation ( oder über die relative URL /admin/api ) erreicht werden.

Sie finden dort interaktive Dokumentationen. Die Dokumentationen können dort dann als Open-API-Spezifikation zur Verwendung mit verschiedenen REST-Clients (z. B. Postman) heruntergeladen werden.

Weitere Details (z. B. auch zur Try-it-out-Funktion) finden Sie unter API 2.0 Dokumentation PORTAL.

3. Autorisierung

Bei der Zugangskontrolle handelt es sich um eine Implementierung nach dem OAuth V2 Standart. Auf die Details des Protokolls wird im Folgenden nicht eingegangen, stattdessen wird anhand von Beispielen demonstriert, wie die API zum Anfordern von Access Token verwendet werden kann.

Dateistrukturen

AccesToken

{
"access_token": <string>, // Das Access Token
"expires_in": <int>, // Zeitraum in Sekunden, die das Token gültig ist
"token_type": <string>, // i.d.R. "bearer"
"scope": <string> // Liste der zugewiesenen Scopes, mit Leerzeichen getrennt
}

Workflow

Das Anfordern von Access Token über die client_credentials erfordert die obigen Client ID und Client Secret. Die Methode ähnelt dem Benutzer-Login mit Benutzername und Passwort, es wird aber keine Session initialisiert und das Access Token ist auch nicht an einen oder eine Benutzer:in gebunden.

[GET]  /token

4. Verwenden der API

Basis URL

https://domain.tld/api/v2

Alle API-Requests müssen über HTTPS ausgeführt werden. Requests über HTTP werden fehlschlagen. API-Requests ohne Autorisierung werden ebenfalls fehlschlagen.

Weiterführende Hinweise und ergänzende Funktionen finden Sie auch auf den Seiten der Knowledge Base:

• Beitrags API

• Benutzer API

• Guthaben API

• Kleinanzeigen API

• Location API

• Newsletter API

• Printprodukte (Kleinanzeigen) API

• Routing API

• Stellenmarkt API

• Veranstaltungskalender API

Eine HTTP Basic Authentication kann über die URL mitgegeben werden (z. B. https://user:pass@domain.tld/path ). Andere Formen der Authentifizierung beim Download der Bilder sind nicht vorgesehen. 

Das ist abhängig vom Use-Case: Sofern die Bilder aus dem PORTAL zu einem PRINT-System exportiert und dort weiterverwendet werden sollen (z. B. im PEIQ PRINT PPS), sollten sie entsprechend größer angeliefert werden. Ansonsten genügen kleinere Bildgrößen. Als Referenz: Die größte im PORTAL generierte Variante hat 2048px.

Bilder (Image Objekte) werden im PORTAL beim Erstellen fest mit einer Bilddatei verknüpft, es ist nicht möglich, das Objekt beizubehalten und die Datei auszutauschen. Dementsprechend sind Bild-Updates im Sinne einer aktualisierten Bilddatei nur möglich, indem das Bild gelöscht (DELETE) und das neue Bild importiert (POST) wird.