PORTAL und PPS Knowledge Base

Beitrags API

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

Die API des Article Moduls kann zum Abrufen, Erstellen, Editieren und Löschen von Beiträgen, von Schnappschüssen sowie von Kommentaren zu Beiträgen oder Schnappschüssen verwendet werden. Zudem können mithilfe der API Medienstreams mit Beiträgen verknüpft und als Hero-Image gesetzt werden. Bilder werden asynchron importiert. 

Funktionalitäten der Beitrags API

  • Abrufen, Erstellen, Editieren und Löschen von Beiträgen nach verschiedenen Filtern

  • Abrufen, Erstellen, Editieren und Löschen von Schnappschüssen nach verschiedenen Filtern

Inhaltsverzeichnis

Allgemeine Beschreibung

Die API-Dokumentation ist als interaktive Dokumentation für berechtigte Admins direkt im jeweiligen PORTAL unter /admin/api/v2/doc?module=article erreichbar.

Das swagger-File kann auch hier heruntergeladen werden (Stand: Oct 20, 2022):

 

Interaktive Dokumentation im Admin-Bereich des PORTALs

Verfügbare Endpunkte

Article

  • GET /articles: Gibt eine paginierte Liste an Beiträgen nach den gesetzten Filtern aus.

  • GET /articles/{article_id}: Gibt den durch die ID spezifizierten Beitrag zurück.

  • POST /articles: Erstellt einen neuen Beitrag.

  • PUT /articles/{article_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Beitrags.

  • DELETE /articles/{article_id}: Löscht den durch die ID spezifizierten Beitrag unwiderruflich.

Article Category

  • GET /articles/categories: Gibt eine Liste der im PORTAL hinterlegten Kategorien für Beiträge zurück (Informationen: id, name, name_norm).

  • GET /articles/categories/{category_id}: Gibt die durch die ID spezifizierten Kategorie für Beiträge zurück (Informationen: id, name, name_norm).

Article Comment

  • GET /articles/{article_id}/comments: Gibt die Kommentare des durch die ID spezifizierten Beitrags zurück.

  • POST /articles/{article_id}/comments: Erstellt einen Kommentar am durch die ID spezifizierten Beitrag.

  • PUT /articles/comments/{comment_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Kommentars.

  • DELETE /articles/comments/{comment_id}: Löscht den durch die ID spezifizierten Kommentar

Article Image

  • GET /articles/{article_id}/images: Gibt alle Bilder des durch die ID spezifizierten Beitrags zurück

  • GET /articles/images/{image_id}: Gibt das durch die ID spezifizierte Bild eines Beitrags zurück

  • POST /articles/{article_id}/images: Fügt ein oder mehrere Bilder (array) einem durch die ID spezifizierten Beitrag hinzu

  • PUT /articles/images/{image_id}: Aktualisiert die Meta-Informationen (hochgeladen von, Copyright, Bildunterschrift, Bildfokus) des durch die ID spezifizierten Bildes.

  • DELETE /articles/images/{image_id}: Löscht das durch durch die ID spezifizierte Bild eines Beitrags unwiderruflich.

Bilder werden asynchron importiert.

Beachte auch die Hinweise hier: https://peiq.atlassian.net/wiki/spaces/CORE/pages/44400763/API+Cloud-Connect#Fragen-zu-Bilder-Workflows-%C3%BCber-die-APIs

Imagepost

  • GET /imageposts: Gibt eine paginierte Liste an Schnappschüssen nach den gesetzten Filtern aus

  • GET /imageposts/{imagepost_id}: Gibt den durch die ID spezifizierten Schnappschuss zurück

  • POST /imageposts: Erstellt einen neuen Schnappschuss

  • PUT /imageposts/{imagepost_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Schnappschusses.

  • DELETE /imageposts/{imagepost_id}: Löscht den durch die ID spezifizierten Schnappschuss unwiderruflich.

Imagepost Comment

  • GET /imageposts/{imagepost_id}/comments: Gibt die Kommentare des durch die ID spezifizierten Schnapsschusses zurück

  • POST /imageposts/{imagepost_id}/comments: Erstellt einen Kommentar am durch die ID spezifizierten Schnappschuss

  • PUT /imageposts/comments/{comment_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Kommentars.

  • DELETE /imageposts/comments/{comment_id}: Löscht den durch die ID spezifizierten Kommentar

Wichtige Hinweise zum Setzen des Hero-Images

Mit der Beitrags API gibt es die Möglichkeit, auch Medienstreams mit Beiträgen zu verknüpfen sowie als Hero-Image zu setzen.

In diesem Zuge wurde das bisherige thumbnail als DEPRECATED markiert. Zusätzlich wurde hero_image eingeführt, welches sowohl das erste Bild des Beitrags als Vorschaubild, als auch das Vorschaubild des Medienstreams (sofern entsprechend angegeben) als Hero-Image abbilden kann. thumbnail wird von zukünftigen Versionen nicht mehr unterstützt werden.

Wichtige Hinweise zu Embeds, HTML- & BBCode-Tags im Text bei Importen

Wichtige Hinweise zu search_string-Filter bei GET /articles

Der Filter search_string bei GET /articles verhält sich analog der mit den Einstellungen “Diese Wörter” und “mit Beitrags-Text”. Wird nach einem search_string gefiltert, gibt die API zusätzlich die search_highlights aus. Damit können die Snippets und die Highlight-Markierung, die aus der bekannt sind, auch externen Systemen zur Verarbeitung zur Verfügung gestellt werden.

Trouble Shooting bei HTTP Status Codes

400 - Bad Request

404 - Not Found

Verwandte Seiten