1. Flip Support
  2. Für Administrator:innen
  3. Sync und Post API

Beitrags-API: Lesen von Beiträgen, Kommentaren und Anhängen

Du findest eine Spezifikation zum Abrufen von Posts und Kommentaren über den folgenden Link:
Die Nutzung der Post API erfolgt in der Regel in den folgenden Schritten:
  1. Token abrufen
  2. Posts im gewünschten Zeitraum abrufen
  3. Details zu den relevanten Posts abrufen
  4. Anhänge herunterladen

OAuth2-Token abrufen

Für alle Anfragen an die Post API musst Du den AuthorizationHeader mit einem gültigen Token setzen. Bevor Du also Anfragen an die API selbst stellst, musst Du ein Token abrufen. Die Authentifizierung basiert auf OAuth2 mit demgrant_type password. Dieclient_id muss auf client_id gesetzt werden.
Anfrage:
Stelle sicher, dass Du alle Werte, die mit „$“ beginnen, durch Deine eigenen Werte ersetzt, wie oben beschrieben:
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"
Antwort:
{
  "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"
}
Jetzt musst Du den Inhalt des Feldes access_token speichern, da er für die folgenden Anfragen an die API benötigt wird. Das Token hat eine definierte Ablaufzeit, expires_in, und kann für diesen Zeitraum verwendet werden. Es ist also nicht notwendig, für jede Anfrage ein neues Token abzurufen.
Für weitere Informationen über OAuth2 und den grant_type password, siehe https://www.oauth.com/oauth2-servers/access-tokens/password-grant/.

Posts lesen

Alle Posts abrufen, z. B. in einem vollständigen Synchronisierungsszenario

Um eine Liste aller Posts abzurufen, auf die Dein Benutzer zugreifen kann, kannst Du einfach die /posts Route ohne Abfrageparameter aufrufen.
Anfrage:
curl "<https://$DOMAIN/api/external/post/v1/posts>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"
Antwort:
{
	"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"
		}
	]
}

Posts für einen definierten Zeitraum abrufen

Durch die Verwendung der Abfrageparameter after und/oder before kannst Du die Posts eingrenzen.
Anfrage:
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"

Die neuesten erstellten oder aktualisierten Posts abrufen

Indem Du nur den before Parameter bei dem Aufruf der /posts Route setzt, ändert sich die Reihenfolge. Dies kann verwendet werden, um die letzten, z. B. 20 erstellten oder aktualisierten Posts abzurufen, wenn es in Kombination mit dem limit Abfrageparameter verwendet wird.
Anfrage:
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"

Paginierung und Arbeit mit Cursorn

Falls Deine Anfrage das übersteigt, was Du über den Abfrageparameter oder das Standardlimit gesetzt hast, enthält die Antwort ein Feld next_cursor.
Der Wert von next_cursor kann dann verwendet werden, um die nächste Seite Deiner Anfrage abzurufen, indem Du ihn als Abfrageparameter cursor setzt.
Antwort der vorherigen Anfrage:
{
	"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"
}
Anfrage:
curl "<https://$DOMAIN/api/external/post/v1/posts?cursor=eyJsaW1pdCI6MzAsImxhc3RfdGltZV90b19iZV9leGNsdWRlZCI6IjIwMjItMDEtMjBUMDk6MTA6MzcuMTIyMjkzWiIsImxhc3RfaWRfdG9fYmVfZXhjbHVkZWQiOiJmMTg0NWZkZi1kNGE1LTRhM2YtYmU0ZC05NDMxYTA5NjUyY2YifQ>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"
Wenn Du eine Anfrage mit einem Cursor stellst, werden alle anderen Abfrageparameter durch den Cursor überschrieben. Wenn diese Seite erneut nicht alle von Dir angeforderten Posts enthält, erhältst Du erneut einen neuen Cursor. So kannst Du weitermachen, bis Du die letzte Seite erreichst.
Die Cursors sollten ausschließlich dazu verwendet werden, die Aufrufe zu verketten, um alle benötigten Antworten zu erhalten, sollten jedoch nicht über einen langen Zeitraum hinweg gespeichert und wiederverwendet werden. Obwohl sie kein striktes Ablaufdatum haben, sollten sie nur für einige Stunden wiederverwendet werden.

Post-Details abrufen

Um die Details wie Inhalt, Autor oder Kanal (in dieser API "group" genannt) der Posts zu erhalten, musst Du die Route /post/{id} mit der id der Posts aus den anderen Anfragen aufrufen.
Anfrage:
curl "<https://$DOMAIN/api/external/post/v1/post/29794b71-e80b-432d-89e0-e8339ac4a3b4>" -H "Accept: application/json" -H "Authorization: Bearer $access_token"
Antwort:
{
	"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>"
	}
}

 

Wenn ein Beitrag nicht mehr verfügbar ist, weil er gelöscht wurde, erhalten Sie stattdessen eine HTTP 404 als Antwort.

Anhänge

Wenn einem Beitrag Anlagen beigefügt sind, werden diese in der Antwort auf den Aufruf der Beitragsdetails angezeigt.

Antwort:

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

Die Anhänge enthalten einen vollständigen Link zu der Datei. In diesem Fall ist Ihre Domäne bereits festgelegt, so dass der Link so verwendet werden kann, wie er ist. Die Authorization muss mit dem Token ausgefüllt werden, so wie es bei den anderen Aufrufen gemacht wird.

 

Anfrage:

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

 

Kommentare

Kommentare können für jeden Beitrag einzeln durch Aufruf von /post/{id}/comments abgerufen werden.

Anfrage:

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

Die Antwort enthält dann eine Liste mit allen Kommentaren zu diesem Beitrag. Sie enthält den Kommentar im comment Feld, die Dateien des Kommentars als Anhang und auch Informationen über den Autor usw. Die Paginierung funktioniert genauso wie beim Lesen von Beiträgen und anderen Endpunkten*. Darüber hinaus können die Abfrageparameter "after" und "before" verwendet werden, um die Zeitspanne wie beim Lesen von Beiträgen einzuschränken.

Antwort:

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

War dieser Beitrag hilfreich?

0 von 0 fanden dies hilfreich

Haben Sie Fragen? Anfrage einreichen

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.