Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
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 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 , Schnappschüsse und Kommentare zu Beiträgen oder Schnappschüssen nach verschiedenen Filtern abgerufen werden. Zudem können Medienstreams 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
titleInhaltsverzeichnis anzeigen
Table of Contents
maxLevel4
Grundlegendes zur Beitrags API

Allgemeine Beschreibung

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
colourBlue
titleget

  • Get All Articles by Filters

    • status (Available values : draft, published, rejected, scheduled, deleted)

    • date_filter_type (Available values : published, created, updated ; Default value : published)

    • date_start

    • date_end

    • location_ids

    • user_id

    • user_segment

    • category_ids

    • tags

    • static_tags (Available values: commercial, premium_content)

  • Get Article by ID

    • article_id

Response

Code Block{ "total_results": 234, "total_pages": 12, "page": 1, "page_size": 20, "data": [ { "comments_enabled": true, "news_sitemap": true, "publish_schedule": { "start": "2019-03-07T00:00:00+00:00", "end": "2019-03-27T00:00:00+00:00" }, "remote_id": 1234, "url": "https://www.example.com/augsburg/c-category-a/test-article-1_a1", "id": "1", "status": "draft", "created": "2019-03-07T00:00:00+00:00", "published": "2019-03-07T00:00:00+00:00", "updated": "2019-03-07T00:00:00+00:00", "display_locations": [ [ 17 ] ], "title": "Test Article #1", "comment_count": "24", "static_tags": [ "commercial", "premium_content", "amp" ], "text_elements": { "kicker": "Test Kicker Kicker Kicker Kicker Test", "text": "Test Text Text Test Text Test" }, "user_id": 1, "category_id": 1, "location_id": 17, "thumbnail": { "url": "https://www.example.com/resources/mediadb/article/2019/03/04/1/1_XL.jpg", "remote_id": "1234", "id": "12" }, "image_count": "5", "visit_count": "1235", "like_count": "15", "tags": [ "Tagger", "I'm a Tag" ] } ] }

-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
nameapi_module_article_swagger.json

Image Added

 

Verfügbare Endpunkte

Article

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

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

  • Status
    colourGreen
    title

post
  • Create Article

article_id
  • POST
    /articles: Erstellt einen neuen Beitrag.

  • Status
    colourYellow
    title

put

Update Article by Id

HTTP Status Codes

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

Verfügbare Endpunkte für Article Categories

Code Block
https://domain.tld/api/v2/articles/categories/{category_id}
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
  • PUT
    /articles/{article_id}: Aktualisiert die im Request Body angegebenen Informationen des durch die ID spezifizierten Beitrags.

  • Status
    colourRed
    title

delete
  • Delete Article by Id

    • article_id

Request Body

Code Block
{
  "comments_enabled": true,
  "news_sitemap": true,
  "publish_schedule": {
    "start": "2019-03-07T00:00:00+00:00",
    "end": "2019-03-27T00:00:00+00:00"
  },
  "remote_id": 1234,
  "status": "published",
  "created": "2019-03-07T00:00:00+00:00",
  "published": "2019-03-07T00:00:00+00:00",
  "updated": "2019-03-07T00:00:00+00:00",
  "display_locations": [
    17
  ],
  "title": "Test Article #1",
  "static_tags": [
    "commercial",
    "premium_content",
    "amp"
  ],
  "text_elements": {
    "kicker": "Test Kicker Kicker Kicker Kicker Test",
    "text": "Test Text Text Test Text Test"
  },
  "user_id": 1,
  "category_id": 1,
  "location_id": 17,
  "tags": [
    "Tagger",
    "I'm a Tag"
  ]
}
  • DELETE
    /articles/{article_id}: Löscht den durch die ID spezifizierten Beitrag unwiderruflich.

Article Category

HTTP Status Codes

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

Verfügbare Endpunkte für Article Comments

Code Blockhttps://domain.tld/api/v2
  • Status
    colourBlue
    titleGET
    /articles/categories: Gibt eine Liste der im PORTAL hinterlegten Kategorien für Beiträge zurück (Informationen: id, name, name_norm).

  • Status
    colourBlue
    title

get
  • Get All Article Categories

  • Get Article Category by Id

    • category_id

Response

Code Block
[
  {
    "id": "1",
    "name": "Sport",
    "name_norm": "sport"
  }
]
  • 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
    colourBlue
    titleGET
    /articles/{article_id}/comments

/{comment_id}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
  • : Gibt die Kommentare des durch die ID spezifizierten Beitrags zurück.

  • Status
    colour

Blue

Status
colourGreen
titlepost

  • Create Article Comments

    • article_id

Status
colourYellow
titleput

Update Article Comment

comment_id
  • Green
    title

get
  • Get Article Comments

    • article_id

Response

Code Block
{
  "total_results": 234,
  "total_pages": 12,
  "page": 1,
  "page_size": 20,
  "data": [
    {
      "id": "1",
      "author_id": 1,
      "text": "This is a test comment!",
      "status": "published",
      "position": "1",
      "created": "2019-03-07T00:00:00+00:00",
      "updated": "2019-03-07T00:00:00+00:00"
    }
  ]
}

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.

Verfügbare Endpunkte für Article Images

Code Blockhttps://domain.tld/api/v2/
  • POST
    /articles/{article_id}/comments: Erstellt einen Kommentar am durch die ID spezifizierten Beitrag.

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

  • Status
    colourRed
    title

delete
  • Delete Article Comment

    • comment_id

Request Body

Code Block
[
  {
    "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!"
}
  • DELETE
    /articles/comments/{comment_id}: Löscht den durch die ID spezifizierten Kommentar

Article Image

  • Status
    colourBlue
    titleGET
    /articles/{article_id}/images

/{image_id}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.
  • : Gibt alle Bilder des durch die ID spezifizierten Beitrags zurück

  • Status
    colourBlue
    title

get
  • Get all Article Images for a specific Article

    • article_id

  • Get Article Image by image_id

    • image_id

Response

Code Block[ { "id": "1", "url_set": { "NATIVE": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_NATIVE.jpg", "T": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_T.jpg", "XS": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_XS.jpg", "S": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_S.jpg", "M": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_M.jpg", "L": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_L.jpg", "XL": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_XL.jpg", "XXL": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_XXL.jpg" }, "user_id": 1, "created": "2019-03-07T00:00:00+00:00", "modified": "2019-03-07T00:00:00+00:00", "caption": "Test Image Caption", "copyright": "Test Image Copyright", "focus_x": "2", "focus_y": "3", "remote_id": "1234" } ]article_id
  • GET
    /articles/images/{image_id}: Gibt das durch die ID spezifizierte Bild eines Beitrags zurück

  • Status
    colourGreen
    title

post

Upload Article Images for a specific Article

Status
colourYellow
titleput

  • Update Imagepost by Id

    • imagepost_id

Status
colourRed
titledelete

  • Delete Imagepost by Id

    • imagepost_id

Code Block
{
  "comments_enabled": true,
  "remote_id": 1234,
  "status": "published",
  "created": "2019-03-07T00:00:00+00:00",
  "published": "2019-03-07T00:00:00+00:00",
  "updated": "2019-03-07T00:00:00+00:00",
  "display_locations": [
    17
  ],
  "title": "Test Imagepost #1",
  "static_tags": [
    "commercial",
    "premium"
  ],
  "user_id": 1,
  "location_id": 17,
  "image": [
    {
      "user_id": 1,
      "caption": "Test Image Caption",
      "copyright": "Test Image Copyright",
      "focus_x": "2",
      "focus_y": "3"
    }
  ]
}

HTTP Status Codes

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

Verfügbare Endpunkte für Imagepost Comments

Code Block
https://domain.tld/api/v2/imageposts/{imagepost_id}/comments
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.
  • POST
    /articles/{article_id}/images: Fügt ein oder mehrere Bilder (array) einem durch die ID spezifizierten Beitrag hinzu

  • Status
    colourYellow
    title

put
  • Update Article Image by Image Id

    • image_id

Status
colourRed
titledelete

  • Delete Article Image by Image Id

    • image_id

Request Body

Code Block
[
  {
    "url": "https://www.example.com/resources/mediadb/article/2019/03/04/1/1_XL.jpg",
    "user_id": 1,
    "creation_date": "2019-03-07T00:00:00+00:00",
    "caption": "Test Image Caption",
    "copyright": "Test Image Copyright",
    "focus_x": "2",
    "focus_y": "3"
  }
]
Code Block
{
  "user_id": 1,
  "caption": "Test Image Caption",
  "copyright": "Test Image Copyright",
  "focus_x": "2",
  "focus_y": "3"
}

HTTP Status Codes

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

Verfügbare Endpunkte für Imageposts

Code Block
https://domain.tld/api/v2/imageposts/{imagepost_id}

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
colourBlue
titleget

  • Get All Imageposts by Filters

    • status (Available values : draft, published, rejected, scheduled, deleted)

    • date_filter_type (Available values : published, created, updated ; Default value : published)

    • date_start

    • date_end

    • location_ids

    • user_id

    • user_segment

    • category_id

    • category_ids (als array)

    • tags

    • static_tags (Available values: commercial, premium_content)

  • Get Imagepost by Id

    • imagepost_id

Response

Code Block
{
  "total_results": 234,
  "total_pages": 12,
  "page": 1,
  "page_size": 20,
  "data": [
    {
      "comments_enabled": true,
      "remote_id": 1234,
      "id": "1",
      "status": "draft",
      "created": "2019-03-07T00:00:00+00:00",
      "published": "2019-03-07T00:00:00+00:00",
      "updated": "2019-03-07T00:00:00+00:00",
      "display_locations": [
        [
          17
        ]
      ],
      "title": "Test Imagepost #1",
      "static_tags": "[commercial, premium]",
      "user_id": 1,
      "location_id": 17,
      "image": {
        "id": "1",
        "url_set": {
          "NATIVE": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_NATIVE.jpg",
          "T": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_T.jpg",
          "XS": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_XS.jpg",
          "S": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_S.jpg",
          "M": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_M.jpg",
          "L": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_L.jpg",
          "XL": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_XL.jpg",
          "XXL": "https://www.example.com/resources/mediadb/article/2019/03/27/1/1_XXL.jpg"
        },
        "user_id": 1,
        "created": "2019-03-07T00:00:00+00:00",
        "modified": "2019-03-07T00:00:00+00:00",
        "caption": "Test Image Caption",
        "copyright": "Test Image Copyright",
        "focus_x": "2",
        "focus_y": "3",
        "remote_id": "1234"
      }
    }
  ]
}

Status
colourGreen
titlepost

  • Create Imagepost

Request Body

Code Block
{
  "comments_enabled": true,
  "remote_id": 1234,
  "status": "published",
  "created": "2019-03-07T00:00:00+00:00",
  "published": "2019-03-07T00:00:00+00:00",
  "updated": "2019-03-07T00:00:00+00:00",
  "display_locations": [
    17
  ],
  "title": "Test Imagepost #1",
  "static_tags": [
    "commercial",
    "premium"
  ],
  "user_id": 1,
  "location_id": 17,
  "image": [
    {
      "url": "https://www.example.com/resources/mediadb/article/2019/03/04/1/1_XL.jpg",
      "user_id": 1,
      "creation_date": "2019-03-07T00:00:00+00:00",
      "caption": "Test Image Caption",
      "copyright": "Test Image Copyright",
      "focus_x": "2",
      "focus_y": "3"
    }
  ]
}
  • PUT
    /articles/images/{image_id}: Aktualisiert die Meta-Informationen (hochgeladen von, Copyright, Bildunterschrift, Bildfokus) des durch die ID spezifizierten Bildes.

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

Note

Bilder werden asynchron importiert.

Panel
panelIconIdatlassian-note
panelIcon:note:
bgColor#F4F5F7

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

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

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

  • Status
    colourGreen
    titlePOST
    /imageposts: Erstellt einen neuen Schnappschuss

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

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

Imagepost Comment

  • Status
    colourBlue
    title

get
  • Get Imagepost Comments

    • imagepost_id

Response

Code Block{ "total_results": 234, "total_pages": 12, "page": 1, "page_size": 20, "data": [ { "id": "1", "author_id": 1, "text": "This is a test comment!", "status": "published", "position": "1", "created": "2019-03-07T00:00:00+00:00", "updated": "2019-03-07T00:00:00+00:00" } ] }
  • GET
    /imageposts/{imagepost_id}/comments: Gibt die Kommentare des durch die ID spezifizierten Schnapsschusses zurück

  • Status
    colourGreen
    title

post

Post Imagepost Comments

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

  • Status
    colourYellow
    title

put

Update Imagepost Comment

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

  • Status
    colourRed
    title

delete

Delete Imagepost Comment

  • DELETE
    /imageposts/comments/{comment_id

Request Body

Code Block
[
  {
    "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
languagetext
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
  • }: 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
colourRed
titleDEPRECATED
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

Siehe die entsprechende Dokumentation:

Verwendung von HTML- & BBCode-Tags bei Importen

Trouble Shooting bei HTTP Status Codes

400 - Bad Reqest

Der Request war nicht akzeptabel. Das liegt oft an einem fehlenden Parameter. Hier ist der gesendete Request Body zu prüfen.

404 - Not Found

Der gesuchte Inhalt konnte nicht gefunden werden bzw. die gesetzten Filter finden keine Ergebnisse.

Verwandte Seiten

Filter by label (Content by label)
showLabelsfalse
showSpacefalse
cqllabel in ( "api" , "api-dokumentation" , "schnittstellen" ) and space = "PPSD"

Include Page
Disclaimer der PEIQ PORTAL - Produktdokumentation
Disclaimer der PEIQ PORTAL - Produktdokumentation