Post API: Writing posts

Context of this document: The Flip Post API for posts, comments, and attachments

Please find a specification for handling posts with the link below.

Flip API Documentation - Post

 

The Post API allows you to generate posts automatically from third-party systems, such as the intranet, Sharepoint, or ticket systems.

Benefits:

  • The manual effort required to maintain systems in sync is significantly reduced.
  • Information can be shared quicker, more consistently, and better.

Creating, updating and deleting posts

Please note:

  • The Post API has a rate limit of 3 requests per second. In case of exceeding the rate limit, the API will return the HTTP Status 429.
  • The Post API has a limited body size of 200 KiB. In case of exceeding the limit, the API will return the HTTP Status 400.
  • The group of the group_id must exist and the user, which is used to authenticate for the API, must be a group-member of the group. In case the group only allows posts to be created by admins, the user needs to be an admin as well.

Create a post

To create a post via the API, at least the group_id and the title must be given. Additionally, a body in HTML as well as an external_id can be added. Make sure the HTML of the body is valid. In the case of an invalid HTML, the API returns an error.

Request:

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>!"
}

Response:

The response will contain the ID of the newly created post.

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

This will create the following post in the given group:

Untitled (33).png

Create a post with a file attached

After uploading a file via the attachment endpoint, the attachment_id is returned. This ID can be inserted into the POST request via the attachments array.

In the following example, we create a post after uploading a pdf and a jpeg to the Attachment API.

Request:

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" }
	]
}

Be sure to check the success of the media upload via the Attachment API.

This will create the following post in the given group:

Untitled (32).png

Create a post with inline images & videos

After uploading an image or video via the attachment endpoint, the attachment_id is returned. This attachment_id must then be inserted in the attachments list in the POST request, as well as in the src attribute of the <img>/<video> tag in the HTML body.

In the following example, we create a post with an inline image after uploading a jpeg to the attachment endpoint.

Request:

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" }
	]
}

Be sure to check the success of the media upload via the Attachment API.

Update a post

The post can only be updated by using the post_id and not by the external_id. The group of the post cannot be changed this way.

Request:

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

The post is now changed.

Untitled (31).png

Delete a post

A post can only be deleted by using the post_id and not by the external_id.

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

 

Working with posts by external_id

Specifically, when working with integrations, where post content is provided through a secondary system, the external_id on the post entity can be leveraged.

Please note and keep in mind:

  • There is no enforcement of uniqueness of external_id on any Flip entity.
  • For clarity, external_post_id is used to reference the external_id on the Flip post entity.

Find a post by external_id

To locate a post by external_id, request posts via the corresponding endpoint. Unless it makes sense, keep all other parameters as null. The responding JSON will provide an array of matching Flip post GUIDs along with lifecycle timestamps.

Request:

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

Please note:

  • Should the array be empty, no post by that external_post_id / external_id exists.
  • Should multiple posts be in the array, the integration has not enforced uniqueness. Please handle this behavior on the integration side.

 

Formatting posts

Each post in Flip can have a formatted body. The API allows adding a body to a post as HTML. Because Flip currently does not support all HTML tags, the transmitted HTML will be checked for its validity. This is done partly because of restrictions on what should be shown in the Flip App for user experience, especially on mobile devices.

Two possibilities exist when the HTML is not valid.

  1. The HTML is syntactically invalid. This can be checked by any HTML validator.
  2. Illegal HTML tags are used (see the table below to check for all allowed HTML tags).

In case of an invalid HTML, the API will return specific errors.

Allowed HTML Tags

You can use any of the following HTML tags to format text in your posts.

HTML Tag Name Description
<a> It is termed as anchor tag, and it creates a hyperlink or link.
<b> It is used to make a text bold.
<br> It is used to apply a single line break.
<em> It is used to emphasize the content applied within this element.
<h1> It defines a heading for an HTML document
<h2> It defines a heading for an HTML document
<h3> It defines a heading for an HTML document
<i> It is used to represent a text in some different voice.
<li> It is used to represent items in a list.
<ol> It defines an ordered list of items.
<p> It represents a paragraph in an HTML document.
<s> It renders text which is no longer correct or relevant.
<strong> It is used to define important text.
<u> It is used to render enclosed text with an underline.
<ul> It defines an unordered list of items.
<img> It renders an image

HTML Errors

In case of an invalid HTML, a 400 BAD REQUEST with a json response with two fields error_code and message is returned.

Case ErrorCode ErrorMessage (example)
The HTML markup sent by the client is invalid. INVALID_HTML HTML is invalid
The HTML markup the client sent contains disallowed tags. (example usage of <video> tag) DISALLOWED_TAGS Tag(s) VIDEO are not allowed

In the following are the Responses listed in the json format.

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

Example response to invalid HTML.

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

Response body to a request that included disallowed tags.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.