[2-4] INBOUND OUTBOUND CREATE API

Inhaltsverzeichnis

Funktionalitäten & Endpunkte der CREATE API

Der aktuelle Funktionsumfang kann über das Swagger User Interface eingesehen werden:
https://mt-master-create.peiq.cloud/createapi/createapi.html#/

GET: Abfragen von API Infos

get /createapi/v1/info

Von einem Drittsystem aus können per CREATE API zur Fehleranalyse Infos abgefragt werden, mit welchem Benutzer und welcher Version die API aufgerufen wurde.

Beispiel get Aufruf:

cURL:

Response

GET: Abfragen zuletzt geänderter CREATE-Artikel

get /createapi/v1/articles

Von einem Drittsystem aus können per CREATE API alle zuletzt geänderten CREATE-Artikel aus der Datenbank abgefragt werden. Als Ergebnis wird eine Liste mit IDs ausgegeben.

Mögliche Parameter

• limit: max. Anzahl der Artikel, die gesucht werden sollen (optional)

• eventName: changed (Pflicht)

• offset: Gibt an, wie viele Artikel in der Ergebnisliste am Anfang übersprungen werden sollen (optional)

Beispiel get Aufruf:

cURL:

Response

GET: Abfragen von zuletzt geänderten CREATE-Artikeln mit dem Filter “Kanal” und “Kanal & Status”

get /createapi/v1/articles/events?eventName=changed&channel

Von einem Drittsystem aus können per CREATE API nach zuletzt geänderten CREATE-Artikel nach dem Kanal aus der Datenbank gefiltert und abgefragt werden. Als Ergebnis wird eine Liste mit IDs ausgegeben.

Mögliche Parameter

• Kanal “Online”

• Kanal “Print”

Beispiel get Aufruf:

Response

get /createapi/v1/articles/events?eventName=changed&channel&state

Von einem Drittsystem aus können per CREATE API nach zuletzt geänderten CREATE-Artikel nach dem Kanal und Status aus der Datenbank gefiltert und abgefragt werden. Als Ergebnis wird eine Liste mit IDs ausgegeben.

Mögliche Parameter

• channel=Online

• channel=Print

• state=Erfassung

• state=Publiziert

• state=Revision

Beispiel get Aufruf:

Response

GET: Einzelne CREATE-Artikel abfragen

Alternativ kann auch eine feste Artikel-ID als Variable in der Postman Environment hinterlegt werden.

Mögliche Parameter

• limit: max. Anzahl der Artikel, die gesucht werden sollen

• eventname: changed

• offset oder offsetindex: Gibt an, wie viele Artikel in der Ergebnisliste am Anfang übersprungen werden sollen

Beispiel get Aufruf:

cURL:

Response

Als Ergebnis wird die CID des erstellten Artikels ausgegeben.

POST: CREATE-Artikel anlegen

post /createapi/v1/articles

Von einem Drittsystem aus können per CREATE API alle CREATE-Artikel angelegt werden. Dabei muss der Artikel über die Schnittstelle als gültiges JSON im body als Binärdaten übergeben werden.

Mögliche Parameter

Keine Parameter.

Beispiel post Aufruf:

JSON:

cURL:

Response

Als Ergebnis wird die CID des erstellten Artikels ausgegeben.

PUT: Einzelne Artikel updaten

Über die CREATE API können bereits existierende Artikel aktualisiert werden. Dabei muss die Artikel-CID des CREATE-Artikels im Request angegeben werden.

Im Body müssen alle Daten, die aktualisiert werden sollen, als gültiges JSON übergeben werden.

Eine nicht mit angegebene Variante wird auch nicht geändert.

Wenn im Text etwas aktualisiert werden soll, muss der gesamte Content-Bereich noch einmal mitgeschickt werden. Das heißt, der Text einer Variante/Ausprägung wird beim Update stets überschrieben. Felder, die nicht angegeben werden, werden nicht verändert. Felder, die leer angegeben werden, werden leer gesetzt.

Beim Update kommen keine Daten aus dem Ziel-System zurück:

Beispiel put Aufruf:

cURL:

Response

Als Ergebnis wird die ID des aktualisierten Artikels ausgegeben.

Sonderfall: Artikel-Ausprägung löschen

Wenn im JSON bei einer Ausprägung der Status “Entfernen” angegeben wird, so wird die Ausprägung des CREATE-Artikels gelöscht.

Beim Status “Entfernen” werden auch alle Subvarianten (z. B. Infoboxen), die von der zu löschenden Ausprägung aus referenziert werden, mit gelöscht.

Validierungen beim POST/PUT von CREATE-Artikeln

Validierung Artikel-Daten

Prüfung Pflichtfelder

• Es müssen mind. ‘id’ und ‘template_name’ angegeben werden, damit ein Artikel angelegt wird (type kann weggelassen werden und ist automatisch ‘Main’)

• Bei den ‘contents’-Elementen (z. B. Titel, Unterteil, Paragraph usw.) wird geprüft, ob die notwendigen Daten-Strukturen korrekt angegeben wurden. Bei unbekannten contents-Elementen wird eine entsprechende Fehlermeldung ausgegeben.

• Wenn CIDs von Clustern übergeben werden, wird geprüft, ob der Cluster (image, lead_image, teaser_image, image_gallery, embed, article_link) auch im System vorhanden ist. Gibt es ein Element/Cluster nicht, wird eine entsprechende Fehlermeldung ausgegeben.

• Wenn ein ‘subarticle’ (Infobox, Onlinebox) angegeben wird, muss die ‘variant_id’ angegeben sein und in den Requestdaten muss eine dazu passende variante mit angegeben sein ('variant_id' muss eindeutig sein).

Prüfung Kanal-übergreifender Metadaten (Parametrisierbar)

Es können in der CREATE-API bestimmte Metadaten, deren Inhalt durch PEIQ fest vorgegeben ist - z. B. durch Wertelisten oder Autocompleter, inhaltlich geprüft werden. Werden Artikel-Metadaten bei einem POST oder PUT geschickt, die nicht erlaubt sind, wird ein entsprechender Fehler ausgegeben.

Validierung Kanal-Daten

• ‘channels’: es muss der korrekte Name des Kanals angegeben sein, so wie er in CREATE verwendet wird. Wird ein ungültiger Name angeliefert, wird ein entsprechender Fehler ausgegeben.

• categories pro channel:

  • Den ‘categories’ entspricht ein Mappenpfad imRubrikenbaum. Wenn eine ID angegeben ist, muss ein entsprechender DMappeDigital-Cluster in PRINT NGEN vorhanden sein.

  • Wenn ‘id’ leer ist und ein ‘path’ angegeben ist, wird versucht über den Pfad der DMappeDigital-Cluster zu bestimmen.

Prüfung Kanal-spezifischer Metadaten (Parametrisierbar)

Es können in der CREATE-API bestimmte kanalspezifische Metadaten, die in den KanalInfos (z. B. an der Ausprägung gespeichert werden und deren Inhalt durch PEIQ fest vorgegeben ist - z. B. durch Wertelisten oder Autocompleter, inhaltlich geprüft werden. Werden Artikel-Metadaten bei einem POST oder PUT geschickt, die nicht erlaubt sind, wird ein entsprechender Fehler ausgegeben.

Validierung Ausprägungs-Daten

• variants: Die id der variants (=Ausprägungen ) muss eindeutig sein. Es können also nicht mehrere Ausprägungen mit identischer id angelegt werden.

Bilderhandling

Für das Handling (Anlegen, Abholen, Updaten) der Bilder in CREATE-Artikeln wird die DAM API benötigt.

Beim Anlegen und Updaten von Artikeln wird in der CREATE API - sofern Bilder im Status “Original” angeliefert bzw. im JSON referenziert sind - immer eine Bildkopie erstellt und diese statt des Originals über die Angabe der Bild-CID im Artikel verlinkt. Bilder im Status “Unverschlagwortet” werden abgewiesen.

Abfragen der Bilder in CREATE-Artikeln inkl. Bild-Metadaten

Bilder, die in CREATE-Artikeln verwendet wurden, können inkl. der an den Bild-Clustern gespeicherten Metadaten über die DAM API abgefragt werden.

Über die im CREATE Artikel-JSON referenzierte ID des Artikelbildes, z. B. "id": "202-2119472", kann dieses über eine get Abfrage in der DAM API unter Angabe der entsprechenden Bild-Auflösung (Empfehlung: HighRes) heruntergeladen werden.

Ausführliche Informationen dazu finden sich unter [0-21] PEIQ DAM API | Suche nach bestimmten Bildern.

Beispiel get Aufruf:

Die Metadaten des Bildes können ohne den Zusatz für die Auflösung abgeholt werden.

Beispiel get Aufruf:

Response

Auch das Originalbild der im CREATE-Artikel verwendeten Produktionskopie kann über die DAM API abgefragt werden. Die CID des Originalbildes findet sich in den Metadaten im Attribut "original_id": "DBild/205-4284773" wieder.

Bild-File sowie die zugehörigen Metadaten können analog zu den oben genannten get Aufrufen abgefragt bzw. heruntergeladen werden.

Handling von Infoboxen/Onlineboxen

• get: Infoboxen und Onlineboxen sind über “type”: “OnlineBox” bzw. “type”: “InfoBox” identifizierbar und können so eindeutig zugeordnet werden. Es können mehrere Onlineboxen in einem CREATE-Artikel enthalten sein und abgeholt werden.

• post: Es können im Moment mehrere Infoboxen angelegt werden. Standardmäßig ist in den CREATE-Templates jedoch in der Regel nur eine Infobox. Weitere Infoboxen/Onlineboxen werden folglich herausgefiltert, da aktuell alle Elemente, die im Template nicht erlaubt sind, gemäß Artikel-Templates und Freiheitsgrade, entfernt werden.

Komponenten der Schnittstelle

Masken

• DamAPI.dll

• CreateUtils.dll

• ApiUtils.dll

• NGenWebServices.dll

• CreateAPI.dll

• CommonUtils.dll

Tokens zur Autorisierung und Authentifizierung in der CREATE API

siehe dazu:

Maßgebliche DB-Tabellen

DBild, DText, DEmbed

Mitwirkungspflichten

Schnittstelleneinrichtung des Drittanbieters.

Verwandte Seiten

Nur für PEIQ-Mitarbeiter:

https://peiq.atlassian.net/wiki/spaces/CORE/pages/209060009