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.
Über die Endpunkte der Beitrags API können die im PORTAL vorliegenden Beiträge und Schnappschüsse nach verschiedenen Filtern abgerufen 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
Expand
title
Inhaltsverzeichnis anzeigen
Table of Contents
maxLevel
4
Grundlegendes zur Beitrags API
Die Beitrags API ist der API Endpunkt der Beiträge & Schnappschüsse. Über die unten genannten Endpunkte können die im PORTAL vorliegenden Beiträge und Schnappschüsse nach verschiedenen Filtern abgerufen werden. Außerdem können Inhalte und dazugehörige Bilder und Kommentare angelegt, geupdatet oder gelöscht werden.
Verfügbare Endpunkte für Articles
Der untenstehende Response-Body zeigt die Struktur eines kompletten Beitrags. Neben dem Inhalt finden sich an diesem Objekt verschiedene Informationen zum Erstellungszeitpunkt, dem bzw. der Autor:in und der Einordnung in PORTAL nach Ortsstruktur.
Mit static_tags lässt sich ein Beitrag oder auch ein Schnappschuss als kommerzieller oder als Premium-Inhalt markieren. Mit den Countern für Kommentare & Likes kann das Engagement der User für jeden Artikel herausgelesen und analysiert werden.
Status
colour
Blue
title
get
Get All Articles by Filters
status (Available values : draft, published, rejected, scheduled, deleted)
200 - Success Alles hat wie erwartet funktioniert
201 - Article Successfully created / deleted
204 - Article Successfully updated
400 - Bad Reqest Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Checken Sie hierfür den gesendeten Request Body.
404 - Article Not Found Der Beitrag mit der angegebenen ID scheint nicht zu existieren.
Kategorien werden von PEIQ im Rahmen des Set-up oder während der Laufzeit eingepflegt. Sie können über diesen Endpunkt einfach ausgelesen und verwendet werden. Zusätzlich kann man mehrere Kategorien als array, über category_ids, abrufen.
200 - Success Alles hat wie erwartet funktioniert
400 - Bad Reqest Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Checken Sie hierfür den gesendeten Request Body.
404 - Category Not Found Die Kategorie mit der angegebenen ID scheint nicht zu existieren.
Beiträge können kommentiert werden. Dieser Endpunkt ermöglicht es, die vorliegenden Kommentare für einzelne Artikel zu lesen oder auch Kommentare zu posten, zu updaten oder zu löschen.
[
{
"author_id": 1,
"text": "This is a test comment!",
"created": "2019-03-07T00:00:00+00:00"
}
]
Code Block
{
"status": "published",
"text": "This is a modified test comment!"
}
HTTP Status Codes
Code Block
200 - Success Alles hat wie erwartet funktioniert
201 - Comment Successfully created / deleted
204 - Comment Successfully updated
400 - Bad Reqest Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Checken Sie hierfür den gesendeten Request Body.
404 - Comment / Article Not Found Der Kommentar / Beitrag mit der angegebenen ID scheint nicht zu existieren.
Dieser Endpunkt ermöglicht es Bilder an Beiträgen zu lesen oder auch hinzuzufügen (z. B. von einer externen Ressource oder aus einer Bildersammlung), zu updaten oder zu löschen. Mit dem Parameter caption kann eine Bildunterschrift vergeben werden. Der Parameter copyright befüllt die Information zum Urheber.
200 - Success Alles hat wie erwartet funktioniert
201 - Image Successfully uploaded / deleted
204 - Image Successfully updated
400 - Bad Reqest Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Checken Sie hierfür den gesendeten Request Body.
404 - Article Images Not Found Der Kommentar / Beitrag mit der angegebenen ID scheint nicht zu existieren.
Der untenstehende Response-Body zeigt die Struktur eines kompletten Schnappschusses. Der Inhalt ist hier im Gegensatz zum Beitrag nur ein Bild (in verschiedenen Auflösungen) und ein Titel. Daneben finden sich an diesem Objekt verschiedene Informationen zum Erstellungszeitpunkt, dem bzw. der Autor:in und der Einordnung ins PORTAL nach Ortsstruktur und Kategorien im Nachrichtenmodul. Mit static_tags lässt sich ein Schnappschuss als kommerzieller oder als Premium-Inhalt markieren. Mit den Countern für Kommentare & Likes kann das Engagement der Leser:innen für jeden Schnappschuss herausgelesen und analysiert werden.
Status
colour
Blue
title
get
Get All Imageposts by Filters
status (Available values : draft, published, rejected, scheduled, deleted)
200 - Success Alles hat wie erwartet funktioniert
201 - Imagepost Successfully uploaded / deleted
204 - Imagepost Successfully updated
400 - Bad Reqest Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Checken Sie hierfür den gesendeten Request Body.
404 - Imageposts Not Found Der Schnappschuss mit der angegebenen ID scheint nicht zu existieren.
Schnappschüsse können kommentiert werden. Dieser Endpunkt ermöglicht es, die vorliegenden Kommentare für einzelne Schnappschüsse zu lesen oder auch Kommentare zu posten/ zu updaten/ zu löschen.
[
{
"author_id": 1,
"text": "This is a test comment!",
"created": "2019-03-07T00:00:00+00:00"
}
]
Code Block
{
"status": "published",
"text": "This is a modified test comment!"
}
HTTP Status Codes
Code Block
language
text
200 - Success Alles hat wie erwartet funktioniert
201 - Imagepost Comment Successfully uploaded / deleted
204 - Imagepost Comment Successfully updated
400 - Bad Reqest Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Checken Sie hierfür den gesendeten Request Body.
404 - Imagepost / Comment Not Found Der Schnappschuss / Kommentar mit der angegebenen ID scheint nicht zu existieren.
Verwandte Seiten
Filter by label (Content by label)
showLabels
false
showSpace
false
cql
label in ( "api" , "api-dokumentation" , "schnittstellen" ) and space = "PPSD
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: ):
View file
name
api_module_article_swagger.json
Image Added
Verfügbare Endpunkte
Article
Status
colour
Blue
title
GET
/articles: Gibt eine paginierte Liste an Beiträgen nach den gesetzten Filtern aus.
Status
colour
Blue
title
GET
/articles/{article_id}: Gibt den durch die ID spezifizierten Beitrag zurück.
Status
colour
Green
title
POST
/articles: Erstellt einen neuen Beitrag.
Status
colour
Yellow
title
PUT
/articles/{article_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Beitrags.
Status
colour
Red
title
DELETE
/articles/{article_id}: Löscht den durch die ID spezifizierten Beitrag unwiderruflich.
Article Category
Status
colour
Blue
title
GET
/articles/categories: Gibt eine Liste der im PORTAL hinterlegten Kategorien für Beiträge zurück (Informationen: id, name, name_norm).
Status
colour
Blue
title
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
Status
colour
Blue
title
GET
/articles/{article_id}/comments: Gibt die Kommentare des durch die ID spezifizierten Beitrags zurück.
Status
colour
Green
title
POST
/articles/{article_id}/comments: Erstellt einen Kommentar am durch die ID spezifizierten Beitrag.
Status
colour
Yellow
title
PUT
/articles/comments/{comment_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Kommentars.
Status
colour
Red
title
DELETE
/articles/comments/{comment_id}: Löscht den durch die ID spezifizierten Kommentar
Article Image
Status
colour
Blue
title
GET
/articles/{article_id}/images: Gibt alle Bilder des durch die ID spezifizierten Beitrags zurück
Status
colour
Blue
title
GET
/articles/images/{image_id}: Gibt das durch die ID spezifizierte Bild eines Beitrags zurück
Status
colour
Green
title
POST
/articles/{article_id}/images: Fügt ein oder mehrere Bilder (array) einem durch die ID spezifizierten Beitrag hinzu
Status
colour
Yellow
title
PUT
/articles/images/{image_id}: Aktualisiert die Meta-Informationen (hochgeladen von, Copyright, Bildunterschrift, Bildfokus) des durch die ID spezifizierten Bildes.
Status
colour
Red
title
DELETE
/articles/images/{image_id}: Löscht das durch durch die ID spezifizierte Bild eines Beitrags unwiderruflich.
/imageposts: Gibt eine paginierte Liste an Schnappschüssen nach den gesetzten Filtern aus
Status
colour
Blue
title
GET
/imageposts/{imagepost_id}: Gibt den durch die ID spezifizierten Schnappschuss zurück
Status
colour
Green
title
POST
/imageposts: Erstellt einen neuen Schnappschuss
Status
colour
Yellow
title
PUT
/imageposts/{imagepost_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Schnappschusses.
Status
colour
Red
title
DELETE
/imageposts/{imagepost_id}: Löscht den durch die ID spezifizierten Schnappschuss unwiderruflich.
Imagepost Comment
Status
colour
Blue
title
GET
/imageposts/{imagepost_id}/comments: Gibt die Kommentare des durch die ID spezifizierten Schnapsschusses zurück
Status
colour
Green
title
POST
/imageposts/{imagepost_id}/comments: Erstellt einen Kommentar am durch die ID spezifizierten Schnappschuss
Status
colour
Yellow
title
PUT
/imageposts/comments/{comment_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Kommentars.
Status
colour
Red
title
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
Status
colour
Red
title
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
/articles verhält sich analog der Suche in der Beitragsverwaltung 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 Suche in der Beitragsverwaltung bekannt sind, auch externen Systemen zur Verarbeitung zur Verfügung gestellt werden.