Info

Mithilfe der PEIQ Cloud-Connect APIs(engl. Application Programming Interfaces, Programmierschnittstellen) können Verlage Teile ihrer bestehenden Systeme und Produkte mit dem PEIQ Portal PORTAL verbinden. Alle Cloud-Connect APIs sind nach der REST-Architektur aufgebaut. Der Zugriff erfolgt dadurch mit den Standard HTTP-Methoden GET, POST, PUT und DELETE. Die Zugriffskontrolle erfolgt hierbei über eine Implementierung nach OAuth V2 Standard.

Die Dokumentation der Gogol Cloud-Connect API kann von berechtigten Benutzer:innen über die Administration & Moderation oder unter /admin/api oder über das Benutzermenü → Administration & Moderation → API 2.0 BETA Dokumentation aufgerufen werden. Hier steht eine interaktive Entwicklerdokumentation zur Verfügung.

...

Anbindung bestehenden Systeme und Produkte
Interaktive Entwicklerdokumentation mit potentiellen potenziellen Anwendungsmöglichkeiten der verfügbaren APIs
Verwendung des OAuth - V2 - Standards für die Zugriffskontrolle
Einfache Nutzung dank “Try it out”-Funktion

Inhaltsverzeichnis

Expand

title	Inhaltsverzeichnis anzeigen

Table of Contents

maxLevel	4

...

Dokumentation zur PEIQ Cloud-Connect API

Die Dokumentation zur PEIQ Cloud-Connect API Dokumentation kann im Portal PORTAL über die “Administration & Moderation” erreicht werden. Unter dem Menüpunkt “API 2.0 BETA Dokumentation” findet sich eine interaktive Entwicklerdokumentation, die eine Übersicht der potentiellen potenziellen Anwendungsmöglichkeiten der diversen APIs im PEIQ Portal PORTAL bietet. Voraussetzung für den Zugang zur interaktiven Dokumentation ist die Berechtigung “Zugang zur API-Dokumentation”.

Modulübersicht

Die Modulübersicht zeigt auf einen BlickNäheres hierzu siehe API 2.0 Dokumentation PORTAL.

Verfügbare APIs im PEIQ PORTAL

Grundsätzlich stehen all diejenigen APIs zur Verfügung, deren zugehöriges Modul im jeweiligen PORTAL aktiv ist. Einen Überblick, welche Module im jeweiligen Portal PORTAL aktiv und damit auch welche APIs potenziell verfügbar sind. Um eine API benutzen zu können, muss diese für das jeweilige Modul jedoch von PEIQ eingerichtet werden.

Requests und Autorisierung

Die Zugriffskontrolle erfolgt über eine Implementierung nach OAuth-V2-Standard. , bietet die Modulübersicht. Diese steht unter API 2.0 BETA Dokumentation in der Administration & Moderation zur Verfügung. Näheres siehe API 2.0 Dokumentation PORTAL.

Basis URL

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

Alle API Requests müssen über HTTPS gesendet werden. Requests über HTTP schlagen fehl. API Requests ohne Autorisierung werden ebenfalls fehlschlagen.

Findet die Konnektierung der API über eine htaccess-geschützte Staging-Umgebung statt, muss eine IP-Freigabe (oder Netzwerkfreigabe, z. B. falls mehrere Entwickler:innen aus dem gleichen Netzwerk zugreifen wollen) erfolgen. Dazu bitte an das PEIQ Support Team wenden.

Autorisierung

Um Zugriff auf die API zu erhalten, ist ein API Key notwendig, der von PEIQ generiert werden muss.

“Try it out”-Funktion

Die Dokumentation selbst ist nicht nur rein informativer Natur, sondern bietet darüber hinaus die Möglichkeit, sämtliche API-GET-Endpunkte direkt zu testen. Über diese “Try it out”-Funktion können also Live-Daten aus dem System direkt im JSON-Format exportiert werden. Über die “Try it out”-Funktion können auch noch nicht freigeschaltene APIs unverbindlich getestet werden.

Verfügbare APIs im PEIQ Portal

Location-API
Beitrags-API
Newsletter API
Benutzer API
Routing-API
Veranstaltungskalender-API
Kleinanzeigenmarkt-API
Stellenmarkt API
Federation API Beitrag

Expand

title	Formular: Editieren/ Deaktiveren/ Hinzufügen des API-Zugangs

Übergabe API-Zugang

[Name des Zugangs]

client id:

client secret:

aktive API

Lesend

Schreibend

Beitrags-API

Location-API

User-API

t.b.a.

Legende: “1” = aktiv, “0” = inaktiv, “-” = nicht vorhanden

1. Editieren/ Deaktiveren/ Hinzufügen des API-Zugangs

Um einen API-Zugang zu Editieren/ Deaktivieren oder Hinzuzufügen, kann ein Ticket im PEIQ Service Desk, unter Nennung des API-Zugang Namens, eingestellt werden. Das Löschen oder Anpassen kann dann nach Aufwand erfolgen.

2. Wichtige Hinweise:

Der API-Zugang kann Livedaten beeinflussen und sollte entsprechend sorgsam eingesetzt bzw. vom Kunden Dritten zur Verfügung gestellt wird ein Token benötigt. Dieses kann über einen speziellen Endpunkt generiert werden, indem sich mit Client ID und Client Secret authentifiziert wird.

Diese API Credentials (Client ID und Client Secret) können

über die Verwaltung von API-Zugängen von berechtigten Benutzer:innen selbst erstellt werden: API Zugänge verwalten
über eine Änderungsanfrage beim Service Desk beantragt werden, sofern das Feature API-Konsole nicht aktiviert ist.

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

Auch zur Nutzung der Try it out Funktion in der API 2.0 Dokumentation PORTAL ist eine Authentifizierung erforderlich. Diese kann über den grünen Button “Authorize” in jedem Modul über folgende Maske eingegeben und bestätigt werden.

...

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

Anleitung zum Set-up

Expand

title	Schritte nach Aktivierung des API-Managements durch PEIQ

Note

Sie benötigen zum Set-up die Berechtigungsrollen:

Allgemein: Zugang zur Verwaltungsübersicht
API Dokumentation: Alle Berechtigungsrollen unter “Administration”
API-Zugang: Alle Berechtigungsrollen unter “Administration”

Es hat sich bewährt, für diese Art der Berechtigungen eine eigene Berechtigungsgruppe (z. B. Developer) anzulegen und diese ausgewählten Benutzer:innen zu Verfügung zu stellen.

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

Note
Bitte beachten Sie auch die dort gegebenen Hinweise zur Verwaltung der Zugänge.

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

Note
Die API-Credentials können als “read-only” oder “read-and-write” eingerichtet werden. Bei einem “read-and-write”-Modus können die Livedaten beeinflusst - geändert/gelöscht - werden. Aus diesem Grund sollten diese Credentials für “read-and-write”-Zugänge nur an vertrauenswürden Dritte weitergegeben werden. Wird Dritten der API-Zugang

...

durch den oder die Kund:in zur Verfügung gestellt, wird empfohlen, dass der

...

oder die Kund:in eigenständig mit diesen Dritten einen

...

AVV (Vertrag zur

...

Auftragsverarbeitung) abschließt.
Über die

...

Benutzer-API können nutzerbezogene Daten bezogen

...

und (bei read-and-write) auch verändert werden.

...

2. Zugang zur API

...

Benutzer der Onlineplattform, mit entsprechender Berechtigung, erhalten Zugang zur API-Dokumentation

...

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.

Scope	N/A
Bundle Preﬁx	/oauth/v2
Beispiel URL	/oauth/v2/token

Dateistrukturen

AccesToken

Code Block

{
"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.

Note
Achtung: Da diese Access Token mit System-Rechten ausgestattet und dementsprechend sehr mächtig sind, sollten sie niemals das Backend verlassen oder über unsicheren Wege verschickt werden.

Methode:

Code Block
[GET] /token

Parameter:

grant_type Muss immer den Wert client_credentials haben
client_id Die Client / Public ID
client_secret Das Secret (Passwort)

Rückgabewert:

Eine AccessToken Datenstruktur (siehe oben).

Note
Es wird bei jedem `GET` Request ein neues Token erstellt, auch wenn das zuvor angeforderte noch gültig ist. Um unnötige Requests zu vermeiden, sollten einmal angeforderte Token trotzdem so lange verwendet werden, wie sie gültig sind.

4. Verwenden der API

Basis URL

Code Block
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:

FAQs

Zu Bilder-Workflows über die APIs:

Expand

title	Ist für das Abholen von Bildern über eine Dritt-API eine Authentifizierung (z.B. Basic-Authentification) vorgesehen?

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.

Expand

title	Was sollte die maximale Auflösung der zu importierenden Bilder sein?

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.

Expand

title	Kann beim Update eines Image mit "PUT" tatsächlich keine "url" angegeben werden?

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.

Versions Compared

Old Version 11

New Version Current

Key

Dokumentation zur PEIQ Cloud-Connect API

Modulübersicht

Verfügbare APIs im PEIQ PORTAL

Requests und Autorisierung

Basis URL

Autorisierung

“Try it out”-Funktion

Verfügbare APIs im PEIQ Portal

Übergabe API-Zugang

1. Editieren/ Deaktiveren/ Hinzufügen des API-Zugangs

2. Wichtige Hinweise:

Anleitung zum Set-up

1. Einrichtung der API-Zugänge / Autorisierungsdaten

2. Zugang zur API

Dokumentation 2.0 BETA

3. Autorisierung

Dateistrukturen

AccesToken

Workflow

4. Verwenden der API

FAQs

Verwandte Seiten

Page Comparison

Versions Compared

Old Version 11

New Version Current

Key

Dokumentation zur PEIQ Cloud-Connect API

Modulübersicht

Verfügbare APIs im PEIQ PORTAL

Requests und Autorisierung

Basis URL

Autorisierung

“Try it out”-Funktion

Verfügbare APIs im PEIQ Portal

Übergabe API-Zugang

1. Editieren/ Deaktiveren/ Hinzufügen des API-Zugangs

2. Wichtige Hinweise:

Anleitung zum Set-up

1. Einrichtung der API-Zugänge / Autorisierungsdaten

2. Zugang zur API

Dokumentation 2.0 BETA

3. Autorisierung

Dateistrukturen

AccesToken

Workflow

4. Verwenden der API

FAQs

Verwandte Seiten