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

Please find a specification for reading posts, comments with the link below.

Flip API Documentation - Post

Using the Post API will usually be accomplished in the following steps:

1. Get a token
2. Get posts in the desired time range
3. Get details for the relevant posts
4. Download attachments

Get an OAuth2 token

For all requests to the Post API, you need to set the Authorization header with a valid token. So before making any calls to the API itself, you need to fetch a token. The authentication is based on OAuth2 using the grant_type password. The client_id must be set to external-content.

Request:

Make sure to replace all values starting with “$” with your values as mentioned above:

curl -X POST --location "<https://$DOMAIN>/auth/realms/$TENANT/protocol/openid-connect/token" \\
    -H "Content-Type: application/x-www-form-urlencoded" \\
    -d "grant_type=password&client_id=external-content&username=$USERNAME&password=$PASSWORD"

Response:

{
  "access_token": "eyJhbG<...>",
  "expires_in": 86400,
  "refresh_expires_in": 10800,
  "refresh_token": "eyJhbG<...>",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "c85a7b5c-ec06-4038-bf3c-7fee5748a674",
  "scope": "email profile"
}

You now have to store the content of the field access_token since it will be required for making the following calls to the API. The token has a defined expiration, expires_in and can be used for that time. So it is not necessary to get a new token for each call.

For more information about OAuth2 and the grant_type password, see https://www.oauth.com/oauth2-servers/access-tokens/password-grant/.

Reading posts

Get all posts, e.g., in a full sync scenario

To get a list of all posts that your user can access, you can simply call the /posts route without any query parameters.

Request:

curl "<https://$DOMAIN/api/external/post/v1/posts>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"

Response:

{
	"posts": [
		{
			"id": "075a4c3c-d285-4498-a221-1d4895abb5e7",
			"published_at": "2022-01-18T12:27:04.718695Z",
			"updated_at": "2022-01-20T09:11:38.123889Z"
		},
		{
			"id": "3ef1f74f-412a-480f-a315-38a2fc14ec60",
			"published_at": "2022-01-18T12:27:12.205555Z"
		},
		{
			"id": "a6f02553-3b96-425e-aec3-7e841bc14457",
			"published_at": "2022-01-18T12:27:17.814976Z",
			"deleted_at": "2022-01-20T10:07:58.902128Z"
		},
		{
			"id": "f1845fdf-d4a5-4a3f-be4d-9431a09652cf",
			"published_at": "2022-01-20T09:10:37.122293Z"
		},
		{
			"id": "8d706b02-80d3-45b6-8eaf-723a513650e2",
			"published_at": "2022-01-20T09:10:43.309624Z"
		}
	]
}

Get posts for a defined time range

By using the query parameters after and/or before you can narrow down the posts.

Request:

curl "<https://$DOMAIN/api/external/post/v1/posts?after=2022-01-20T12:27:05Z&limit=20>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"

Get the latest created or updated posts

By setting only the before parameter to the /posts call the ordering will change. This can be used to get the last, e.g., 20 created or updated posts when used in combination with the limit query parameter.

Request:

curl "https://$DOMAIN/api/external/post/v1/posts?before=2022-01-20T12:27:05Z&limit=20" -H "Accept: application/json" -H "Authorization: Bearer $access_token"

Pagination and working with the cursors

In case of your request exceeding the limit you have set via the query parameter or the default limit, the response will contain a field next_cursor.

The value of next_cursor can then be used to get the following page of your request by setting it as query parameter cursor.

Response from request before:

{
	"posts": [
		{
			"id": "075a4c3c-d285-4498-a221-1d4895abb5e7",
			"published_at": "2022-01-18T12:27:04.718695Z",
			"updated_at": "2022-01-20T09:11:38.123889Z"
		},
		{
			"id": "3ef1f74f-412a-480f-a315-38a2fc14ec60",
			"published_at": "2022-01-18T12:27:12.205555Z"
		}
	],
	"next_cursor": "eyJsaW1pdCI6MiwibGFzdF90aW1lX3RvX2JlX2V4Y2x1ZGVkIjoiMjAyMi0wMS0xOFQxMjoyNzoxMi4yMDU1NTVaIiwibGFzdF9pZF90b19iZV9leGNsdWRlZCI6IjNlZjFmNzRmLTQxMmEtNDgwZi1hMzE1LTM4YTJmYzE0ZWM2MCJ9"
}

Request:

curl "<https://$DOMAIN/api/external/post/v1/posts?cursor=eyJsaW1pdCI6MzAsImxhc3RfdGltZV90b19iZV9leGNsdWRlZCI6IjIwMjItMDEtMjBUMDk6MTA6MzcuMTIyMjkzWiIsImxhc3RfaWRfdG9fYmVfZXhjbHVkZWQiOiJmMTg0NWZkZi1kNGE1LTRhM2YtYmU0ZC05NDMxYTA5NjUyY2YifQ>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"

When making a call with a cursor, all other query parameters will be overwritten by the cursor. If this page again did not fit all the posts you have requested, you will once more get a new cursor. This allows you to continue this until you reach the last page.

The cursors should exclusively be used for chaining the calls to get all the required responses but should not be persisted over a long time and to be reused. While they do not have a strict expiration, they should only be reused for some hours.

Get the post details

To get the details like content, author, or channel (called “group” in this API) of the posts you will need to call the /post/{id} route with the id of the posts from the other requests.

Request:

curl "<https://$DOMAIN/api/external/post/v1/post/29794b71-e80b-432d-89e0-e8339ac4a3b4>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"

Response:

{
	"id": "3ef1f74f-412a-480f-a315-38a2fc14ec60",
	"group": {
		"id": "a1fd5f9b-d3d5-4e82-8f7b-41058a073134",
		"name": "Test Group"
	},
	"author": {
		"id": "dffa6654-1607-4b13-99e6-9b8267604921",
		"first_name": "Max",
		"last_name": "Müller"
	},
	"info": {
		"published_at": "2022-01-18T12:27:12.205555Z"
	},
"content": {
		"title": "Test",
		"body": "<p>Hallo</p>"
	}
}

If a post is not available any more because it was deleted, you will get an HTTP 404 instead as a response.

Attachments

If there are any attachments to a post, they will be present in the response to the post details call.

Response:

{
	"id": "cf241b36-25f7-4927-8a58-b532a7854b7d",
	"group": {
		"id": "a1fd5f9b-d3d5-4e82-8f7b-41058a073134",
		"name": "Test Group"
	},
	"author": {
		"id": "dffa6654-1607-4b13-99e6-9b8267604921",
		"first_name": "Max",
		"last_name": "Müller"
	},
	"info": {
		"published_at": "2022-01-20T12:49:12.268259Z"
	},
	"content": {
		"title": "Example with Attachment"
	},
	"attachments": [
		{
			"filename": "test.jpg",
			"link": "<https://test.flip-app.com/media/groups/e87cf3a8-2b9f-41a1-a7ed-e44989bb41d1/f437f92f-b4b1-46cc-9c37-f7cd07b50731>",
			"mime_type": "image/jpeg"
		}
	]
}

The attachments have a full link to the file. In that case, your domain will already be set, so the link can be used as it is. The Authorization must be filled with the token in the same way it is done for the other calls.

Request:

curl "<https://test.flip-app.com/media/groups/e87cf3a8-2b9f-41a1-a7ed-e44989bb41d1/f437f92f-b4b1-46cc-9c37-f7cd07b50731>" -H "Authorization: Bearer $TOKEN" -o attachment.jpg

Comments

Comments can be fetched for each Post individually by calling /post/{id}/comments.

Request:

curl "<https://$DOMAIN/api/external/post/v1/post/29794b71-e80b-432d-89e0-e8339ac4a3b4/comments>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"

The response will then contain a list of all the comments for this post. It contains the comment in the comment field, the files from the comment as attachment and also information about the author etc. The pagination works the same, as it’s used for reading posts and other endpoints*.* Furthermore, the query parameters after and before can be used to limit the time range in the same way as reading posts.

Response

{
  "comments": [
    {
      "id": "8bbe8f11-ac62-48b2-9965-168070e75465",
      "author": {
        "id": "bec5af70-ac70-49f1-843c-0da3aa83002b",
        "first_name": "Chuck",
        "last_name": "Norris"
      },
      "created_at": "2022-03-18T15:20:01.831661Z",
      "comment": "test comment"
    },
    {
      "id": "5b418048-a7a0-4c39-87f4-5f90eb93ab16",
      "author": {
        "id": "bec5af70-ac70-49f1-843c-0da3aa83002b",
        "first_name": "Chuck",
        "last_name": "Norris"
      },
      "created_at": "2022-03-18T15:20:38.138938Z",
      "comment": "test comment with attachment",
      "attachments": [
        {
          "filename": "4063f885-42f6-4ad0-b4a9-933e70ffe8d7.jpg",
          "link": "https://master.flip-app.dev/media/groups/f42b7dd7-8543-45e8-89de-d51bd04ea395/a79d6282-45de-4b50-ae59-763eb785effa",
          "mime_type": "image/jpeg"
        }
      ]
    }
  ]
}