Kontext dieses Dokuments: Die Flip Post API für Beiträge, Kommentare und Anhänge

Eine Spezifikation für die Handhabung von Beiträgen findest du unter dem untenstehenden Link.

Flip API Dokumentation - Post

Die Post-API ermöglicht es, Beiträge automatisch aus Drittsystemen wie dem Intranet, Sharepoint oder Ticketsystemen zu generieren.

Vorteile:

• Der manuelle Aufwand für die Synchronisierung von Systemen wird erheblich reduziert.
• Informationen können schneller, einheitlicher und besser ausgetauscht werden.

Erstellen, Aktualisieren und Löschen von Beiträgen

Bitte beachten Sie:

• Die Post-API hat ein Ratenlimit von 3 Anfragen pro Sekunde. Bei Überschreitung dieser Grenze gibt die API den HTTP-Status 429 zurück.
• Die Post-API hat eine begrenzte Körpergröße von 200 KiB. Bei Überschreitung dieses Limits gibt die API den HTTP-Status 400 zurück.
• Die Gruppe der group_id muss existieren und der Benutzer, der zur Authentifizierung für die API verwendet wird, muss ein Gruppenmitglied der Gruppe sein. Falls die Gruppe nur die Erstellung von Beiträgen durch Administratoren zulässt, muss der Benutzer ebenfalls ein Administrator sein.

Einen Beitrag erstellen

Um einen Beitrag über die API zu erstellen, müssen mindestens die group_idund der title angegeben werden. Zusätzlich kann ein body in HTML sowie eine external_id hinzugefügt werden. Achten Sie darauf, dass das HTML des body gültig ist. Im Falle von ungültigem HTML gibt die API einen Fehler zurück.

Anfrage: 

POST /api/external/post/v1/posts
{
	"group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
	"title": "This is a Headline",
	"body":  "Some content for a post with a word in <b>bold</b>!"
}

Antwort:

Die Antwort enthält die ID des neu erstellten Beitrags.

{
	"post_id": "b19c042c-e8ac-4f4f-9eae-0b201211f7f1"
}

Dadurch wird der folgende Beitrag in der angegebenen Gruppe erstellt:

Einen Beitrag mit einer angehängten Datei erstellen

Nach dem Hochladen einer Datei über den Attachment-Endpunkt wird die attachment_id zurückgegeben. Diese ID kann über das attachmentsArray in die POSTAnforderung eingefügt werden.

Im folgenden Beispiel erstellen wir einen Beitrag nach dem Hochladen einer pdf und einer jpeg Datei über die Attachment-API.

Anfrage:

POST /api/external/post/v1/posts
{
	"group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
	"title": "This is a headline",
	"body": "A post with an image and a file attachment",
	"attachments": [
		{ "attachment_id": "2eb9e54a-3af9-4a9c-94b7-2e76d5a4c052" },
		{ "attachment_id": "1cb43fb1-93d7-41e9-9a0c-af48827995b4" }
	]
}

Stelle sicher, dass du den Erfolg des Medien-Uploads über die Attachment-API überprüfst.

Dadurch wird der folgende Beitrag in der angegebenen Gruppe erstellt:

Einen Beitrag mit Inline-Bildern und Videos erstellen

After uploading an image or video via the attachment endpoint, the attachment_id is returned. Diese attachment_id muss dann in die Liste der Anhänge in der POSTAnforderung sowie in das src Attribut des <img>/<video> Tags im HTML body eingefügt werden

Im folgenden Beispiel erstellen wir einen Beitrag mit einem Inline-Bild, nachdem wir ein jpeg zum Attachment-Endpunkt hochgeladen haben.

Anfrage:

POST /api/external/post/v1/posts
{
	"group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
	"title": "This is a headline",
	"body": "<p>A post with an inline image & video</p><img src='2eb9e54a-3af9-4a9c-94b7-2e76d5a4c052'><video src='1239e54a-1gds-sf4a-94b7-2e76d5a4c892'></video>",
	"attachments": [
		{ "attachment_id": "2eb9e54a-3af9-4a9c-94b7-2e76d5a4c052" },
		{ "attachment_id": "1239e54a-1gds-sf4a-94b7-2e76d5a4c892" }
	]
}

Stelle sicher, dass Sie den Erfolg des Medien-Uploads über die Attachment-API überprüfen.

Einen Beitrag aktualisieren

Der Beitrag kann nur mit der post_id und nicht mit derexternal_id aktualisiert werden. Die Gruppe des Beitrags kann auf diese Weise nicht geändert werden.

Anfrage:

PUT /api/external/post/v1/posts/b19c042c-e8ac-4f4f-9eae-0b201211f7f1
{
	"title": "This is a headline",
	"body":  "Some changed content"
}

Der Beitrag ist jetzt geändert.

Einen Beitrag löschen

Ein Beitrag kann nur mit der post_id gelöscht werden, nicht mit der external_id.

DELETE /api/external/post/v1/posts/b19c042c-e8ac-4f4f-9eae-0b201211f7f1

Arbeiten mit Beiträgen nach external_id

Insbesondere bei der Arbeit mit Integrationen, bei denen Beitragsinhalte über ein sekundäres System bereitgestellt werden, kann die external_id der Beitragsentität genutzt werden.

Bitte beachten Sie und behalten Sie im Hinterkopf:

• Die Einzigartigkeit der external_idfür eine Flip-Entität wird nicht erzwungen.
• Der Klarheit halber wird external_post_id verwendet, um auf die external_id der Flip-Beitragsentität zu verweisen.

Einen Beitrag nach external_id suchen

Um einen Beitrag nach external_id zu finden, fordere Beiträge über den entsprechenden Endpunkt an. Sofern es nicht sinnvoll ist, lasse alle anderen Parameter als null. Die JSON-Antwort liefert ein Array von passendem Flip Post-GUIDs zusammen mit Lebenszyklus-Zeitstempeln.

Anfrage:

GET /api/external/post/v2/posts?external_post_id=<foo>

Bitte beachten:

• Sollte das Array leer sein, existiert kein Beitrag mit dieser external_post_id / external_id.
• Sollten sich mehrere Beiträge im Array befinden, hat die Integration die Eindeutigkeit nicht erzwungen. Bitte behandele dieses Verhalten auf der Seite der Integration.

Formatierung von Beiträgen

Jeder Beitrag in Flip kann einen formatierten Textkörper haben. Die API erlaubt das Hinzufügen eines Textes zu einem Beitrag als HTML. Da Flip derzeit nicht alle HTML-Tags unterstützt, wird das übermittelte HTML auf seine Gültigkeit geprüft. Dies geschieht zum Teil aufgrund von Einschränkungen, was in der Flip-App angezeigt werden sollte, um die Benutzerfreundlichkeit zu erhöhen, insbesondere auf mobilen Geräten.

Es gibt zwei Möglichkeiten, wenn das HTML nicht gültig ist.

1. Das HTML ist syntaktisch ungültig. Dies kann mit jedem HTML-Validator überprüft werden.
2. Es werden unzulässige HTML-Tags verwendet (siehe die Tabelle unten, um alle zulässigen HTML-Tags zu überprüfen).

Im Falle von ungültigem HTML gibt die API spezifische Fehler zurück.

Erlaubte HTML-Tags

Du kannst jeden der folgenden HTML-Tags verwenden, um Text in Beiträgen zu formatieren.

HTML-Fehler

Im Falle eines ungültigen HTML-Fehlers wird eine 400 BAD REQUEST mit einer jsonAntwort mit zwei Feldern error_code und message zurückgegeben.

Im Folgenden sind die Antworten im jsonFormat aufgeführt.

{
	"error_code": "INVALID_HTML",
	"message": "HTML is invalid"
}

Beispielantwort auf ungültigen HTML-Code.

{
    "error_code": "DISALLOWED_TAGS",
    "message": "Tag(s) VIDEO are not allowed"
}

Antwortkörper auf eine Anfrage, die unzulässige Tags enthielt.