JSON-Feed

Der JSON-Feed ermöglicht es, bestimmte Inhalte des PORTALs per URL in Form von JSON-Objekten abzurufen.

Die JavaScript Object Notation (JSON) ist ein kompaktes Datenformat in einer einfach lesbaren Textform und dient dem Zweck des Datenaustausches zwischen Anwendungen.

Der Feed (von engl. to feed – im Sinne von füttern, einspeisen, zuführen) kann für Beiträge & Schnappschüsse und für Veranstaltungen genutzt werden. Durch die Verwaltung können Zugänge für bestimmte Feeds erstellt werden. Es kann z. B. eingestellt werden, welche Inhalte im Feed verfügbar sein sollen. Zugreifbar wird der Feed durch ein im System generiertes Zugriffstoken.

Funktionalitäten des JSON-Feeds

Abrufen von PORTAL-Inhalten im JSON-Format
Flexible Selektion der gewünschten Inhalte
Flexible Handhabung der zugreifbaren Inhalte pro Client
JSON-Feeds im PEIQ PORTAL basieren auf dem neuesten Standard

Inhaltsverzeichnis

1 Allgemeine Beschreibung
2 Erstellung und Verwaltung
3 Zugriff
4 Parameter
5 Bearbeitungsprotokoll
6 Datenstruktur
- 6.1 Beitrag
- 6.2 Schnappschuss
- 6.3 Veranstaltung
- 6.4 Text-Elemente
- 6.5 Benutzer-Elemente
- 6.6 Bild-Elemente
7 Verwandte Seiten

Allgemeine Beschreibung

Im Gegensatz zum RSS-Feeds, bei dem bestimmte Zielseiten des PORTALs in Form einer XML-Struktur extrahiert bzw. gelesen werden können, liegt die Selektion der Inhalte beim JSON-Feed in der Hand des Benutzers bzw. der Benutzerin. Der Output des Feeds sind die selektierten Inhalte als JSON-Objekte, welche dann auf einer Zielseite verarbeitet werden können, z. B. in Form von Teasern o.ä.. Zugriff auf den Feed erhält nur, wer den dafür generierten (aktiven) Zugriffstoken hat.

Erstellung und Verwaltung

Die Erstellung und Verwaltung ist mit der Berechtigung “Zugang zur JSON-Feed-Zugangsverwaltung / Zugänge bearbeiten und löschen” möglich.

Bearbeitungsmaske in der JSON-Feed-Zugangsverwaltung

Die Verwaltung findet sich für berechtigte Benutzer:innen unter /admin/federation/client. Über “Zugang erstellen” lässt sich ein neuer Client für einen JSON-Feed generieren. Bearbeitungs- und Löschvorgänge kann der oder die Benutzer:in über die Übersichtsseite vornehmen.

Eingabefeld zum Erstellen eines neuen Clients

Generell können zwei Zugangsmodi konfiguriert werden

ZUGANG AKTIVIEREN Dieser Modus regelt den generellen Zugriff auf den Feed. Hierüber lässt sich der Zugriff temporär deaktivieren, ohne den Feed löschen zu müssen.

ZUGANG BESCHRÄNKEN Dieser Modus regelt die Selektion der zugreifbaren Inhalte. Ist die Zugriffsbeschränkung aus, können die Daten via der unten genannten URL-Parameter selektiert werden. Wird die Zugriffsbeschränkung eingeschalten, öffnet sich das folgende Formular. Hierüber kann genau spezifiziert werden, auf welche Inhalte der Feed eingeschränkt werden soll.

Auswahlfelder zur Beschränkung der zugreifbaren Inhalte eines Benutzers

Zugriff

Zugriffs-URL für Beiträge und Schnappschüsse:

https://<URL-des-PORTALS.de>/a/federation/<Inhaltsform>.json?access_token=<ZUGRIFFSTOKEN>

Die Inhaltsform ist dabei mit folgenden Parametern zu belegen:

articlesfür Beiträge
imageposts für Schnappschüsse

Zugriffs-URL für Veranstaltungen:

https://<URL-des-PORTALS.de>/event/federation/events.json?access_token=<ZUGRIFFSTOKEN>

Das Zugriffstoken kann für den jeweiligen Feed über die Startseite der Verwaltung abgerufen werden. Über das Schlüssel-Icon wird das Token angezeigt und kann über das erscheinende Copy-Icon kopiert werden.

Bearbeitungsmaske in der JSON-Feed-Zugangsverwaltung

Parameter

Bei einem uneingeschränkten Feed lässt sich die Inhaltsselektion mittels angehängter Parameter steuern, welche hinten an die Grund-URL angehängt werden.

<Grund-URL-zum-Abrufen-des-Feeds-inklusive-Token>&<Parameter>=<Wert>

z. B. &category=sport

Folgende Parameter stehen zur Verfügung:

category Eine durch Komma getrennte Liste von normalisierten Kategorien, anhand deren die Beiträge gefiltert werden.
tag Eine durch Komma getrennte Liste von normalisierten Tags, anhand deren die Beiträge gefiltert werden. Mehrere Tags werden als OR Verknüpfung verwendet, es wird keine Schnittmenge aller angegebenen Tags gebildet.
location Eine durch Komma getrennte Liste von normalisierten Ortsnamen, anhand deren die Beiträge gefiltert werden.
limit Maximale Anzahl von zurück gelieferten Beiträgen. Der Default-Wert ist 10, maximal ist ein Wert von 100 erlaubt.
offset Die Anzahl der Beiträge der aktuellen Selektion, die übersprungen werden sollen.

Aus technischen Gründen darf die Summe von limit und offset den Wert 10.000 nicht überschreiten. Andernfalls liefert die API den HTTP Code 400 (Bad Request) zurück.

Bearbeitungsprotokoll

Über das Bearbeitungsprotokoll lässt sich nachvollziehen, wer, wann einen Zugang erstellt, bearbeitet oder gelöscht hat. Das Bearbeitungsprotokoll findet sich in der Verwaltung über das Optionsmenü.

Listenansicht des Bearbeitungsprotokolls

Datenstruktur

Im Gegensatz zur API (Cloud-Connect) werden die Daten beim JSON-Feed in Plain Text ausgegeben. Hierbei müssen bspw. nicht die Beitrags-ID und zusätzlich noch die jeweiligen Daten dazu gesondert gezogen werden. Die Ausgabe beinhaltet alle Informationen zum vorliegenden Inhalt.

Beitrag

{
   "url": <string>,                        // URL des Beitrags im Portal
   "id": <int>,                            // Beitrags ID
   "created": <timestamp>,                 // Erstellungsdatum
   "published": <timestamp>,               // Veröffentlichungsdatum
   "updated": <timestamp>,                 // Letzte Aktualisierung
   "title": <string>,                      // Beitrags Überschrift
   "comment_count": <int>,                 // Anzahl Kommentare
   "static_tags": [<string>],              // Statische Tags / Flags
   "text_elements": <TextElements>,        // Textelemente
   "user": <User>,                         // Beitrags-Autor / Owner
   "category": <Category>,                 // Beitrags-Kategorie,
   "location": <Location>,                 // Beitrags-Verortung
   "images": [<Image>],                    // Bilder des Beitrags
   "image_count": <int>,                   // Anzahl Bilder
   "tags": [<Tag>],                        // Tags des Beitrags
}

Schnappschuss

{
   "url": <string>,                        // URL des Schnappschuss im Portal
   "id": <int>,                            // Schnappschuss ID
   "created": <timestamp>,                 // Erstellungsdatum
   "published": <timestamp>,               // Veröffentlichungsdatum
   "updated": <timestamp>,                 // Letzte Aktualisierung
   "title": <string>,                      // Schnappschuss Überschrift
   "static_tags": [<string>],              // Statische Tags / Flags
   "image": [<Image>],                     // Bild des Schnappschuss
   "user": <User>,                         // Schnappschuss-Autor / Owner
   "location": <Location>,                 // Schnappschuss-Verortung
   "comment_count": <int>,                 // Anzahl Kommentare
}

Veranstaltung

{
   "url": <string>,                        // URL der Veranstaltung im Portal
   "id": <int>,                            // Veranstaltungs-ID
   "created": <timestamp>,                 // Erstellungsdatum
   "published": <timestamp>,               // Veröffentlichungsdatum
   "image_count": <int>,                   // Anzahl Bilder
   "comment_count": <int>,                 // Anzahl Kommentare
   "title": <string>,                      // Veranstaltungs Überschrift
   "description": <string>,                // Veranstaltungs Beschreibung
   "static_tags": [<string>],              // Statische Tags / Flags
   "category": <Category>,                 // Veranstaltungs-Kategorie,
   "location": <Location>,                 // Veranstaltungs-Verortung
   "user": <User>,                         // Veranstaltungs-Autor / Owner
   "images": [<Image>],                    // Bilder der Veranstaltung
   "tags": [<Tag>],                        // Tags der Veranstaltung
   "eventitem_date": <timestamp>,           // Datum der Veranstaltung
   "event_locations": <location>,           // Veranstaltungs-Ort
}

Text-Elemente

{
   "kicker": <string>,    // Dachzeile
   "text": <string>,      // Beitrags-Text
   "subline": <string>,   // Anreißer-Text
   "teaser": <string>,    // Teaser-Text
}

Der Text enthält HTML- und BBCODE-Elemente des Inhalts. Sind diese auf der Zielseite nicht gewünscht, müssen die Elemente an dieser Stelle herausgezogen werden.

Benutzer-Elemente

{
   "full_name": <string>,      // Der Name des Benutzers
   "user_segment": <string>    // Das Segment des Benutzers
}

Bild-Elemente

{
   "url_set": {
       // Key-Value Liste der einzelnen Bildressourcen (verschiedene Größen)
   },
   "native_width": <int>,      // Native Bildbreite in px
   "native_height": <int>,     // Native Bildhöhe in px
   "aspect_ratio": <float>,    // Seitenverhältnis (Höhe / Breite)
   "focus_x": <int>,           // Relativer Bildfokus-Punkt (X-Achse)
   "focus_y": <int>,           // Relativer Bildfokus-Punkt (Y-Achse)
   "caption": <string>,        // Bildunterschrift
   "copyright": <string>,      // Copyright-Vermerk des Bildes
}