API-Nutzung JSON-API

JSON-API

Token

Wenn Sie eine gültige Anmeldung im FlypSite-Backend haben, können Sie das API-Token auf der Seite Clients ablesen:

  • Klicken Sie auf “edit” in der Spalte “HTML-Injection”
  • In der Zeile “Client-Token” finden Sie das für API-Abrufe benötigte Token.
  • Schalten Sie Ihren Client in den Poll-Modus, um nur die JSON-API zu nutzen. (Achtung: Diese Einstellung ist momentan nur administrativ änderbar.)

Syntax der API-Abrufe

Globale Abrufe:

https://flypsite.appspot.com/v1/{{token}}/{{argument}}.json?{{commit}}

Streamspezifische Abrufe:

https://flypsite.appspot.com/v1/{{token}}/s/{{streamname}}/{{index}}/{{count}}/{{argument}}.json?{{commit}}

Abfolge der Abrufe:

Verpflichtender Start-Abruf, vereindeutigt mit random:

https://flypsite.appspot.com/v1/{{token}}/first.json?872659865

Response:

{
	"revision":4,
	"commit":"403c3b37-d33c-47d7-859f-c57beba31e4f",
	"eventid":3292,
	"user":"a76b496f-05be-41a0-ba70-eec37c141ad3",
	"mode":"poll",
	"ackuser":true
}

Nutzen Sie für alle weiteren Abrufe den Wert commit des jeweils letzten Abrufs.

Initialdatenabruf

https://flypsite.appspot.com/v1/{{token}}/initial.json?{{commit}}

Response:

{
"next":2737,
"eventid":3431,
"frames":[],
"more":true,
"commit":"87d0113b-07fe-4dcb-b7bc-615ae61fa831",
"updates":[
	{},{},{},{},{},{},{},{},{},{},{},{},
	{
		"marked":false, 
		"aired":false, 
		"stream":"out1", 
		"messageupdate":false, 
		"index":2880, 
		"id":"126613885", 
		"eclass":"stream", 
		"message":{ 
			"srvinfo":"",
			"link":"https:\/\/www.youtube.com\/watch?v=J5BpePXtYpI",
			"media":{
				"image":{ 
					"notfound":false,"center":{"x":640,"y":360},"width":1280,"zoom":false,"detail":{"x":0,"width":1280,"y":0,"height":720}, "url":"https:\/\/i.ytimg.com\/vi\/J5BpePXtYpI\/maxresdefault.jpg","height":720
				},
				"av":{
					"duration":0.0,"playerurl":"https:\/\/www.youtube.com\/embed\/J5BpePXtYpI","width":1280,"url":"","height":720
				},
				"service":"youtube",
				"page":{},
				"source":"https:\/\/www.youtube.com\/watch?v=J5BpePXtYpI",
				"id":53252547,
				"type":"video",
				"key":"J5BpePXtYpI"
			},
			"type":"message",
			"layout":"video",
			"size":"base",
			"service":"youtube",
			"srvlink":"",
			"srvid":"",
			"style":"plain",
			"time":"Sun, 21 Mar 2021 09:56:21 +0100",
			"text":"Zur Nacht der Bibliotheken stellt sich der Düsseldorfer Krimiautor Horst Eckert im Gespräch mit Tim Tobias von der Ratinger Stadtbibliothek selbst vor und li...",
			"id":81189822,
			"user":{
				"service":"www", "name":"YouTube", "icon":"https:\/\/www.youtube.com\/s\/desktop\/daaab134\/img\/favicon_32.png", "link":"http:\/\/www.youtube.com\/", "handle":"youtube.com", "style":"", "id":14304695, "hash":673290609, "status":""
			},
			"headline":"Nacht der Bibliotheken - Lesung und Interview mit dem Autor Horst Eckert",
			"info":""
		}
	}
],
"revision":4
}

Neben Verwaltungsinformationen erhalten Sie mit diesem Abruf bereits die Initialbefüllung Ihrer Social Wall. Die Property updates enthält eine Liste der aktuell gültigen Posts.

Eine Nachricht kann dabei in mehreren Listen auftauchen. Ihr Client sollte die Hierarchie envelope > message nicht ignorieren: envelope.stream benennt den Stream, in dem eine Nachricht ausgeliefert wird. Ein envelope enthält eine message mit den eigentlichen Nutzdaten. Wird im FlypSite-Backend ein Post gelöscht (d.h.: aus einer öffentlichen Liste entfernt), so wird ein envelope entfernt. Ändert sich der Text einer Nachricht, so werden messages modifiziert, u.U. in mehreren envelopes.

Properties, die direkt im FlypSite-Publisher geändert werden können (und die Sie z.B. als Klassennamen in Ihrem Client verwenden können, um gestalterische Effekte zu erreichen), sind: message.layout, message.size, message.style.

Wie bei jedem Abruf wird auch hier die Angabe commit für den nächsten Abruf benötigt. Die Property next bezeichnet den Index für den nächsten Paging-Abruf, falls Sie auf out1 weiter-pagen. Die Property more zeigt, ob weitere Nachrichten vorliegen. Speichern Sie die revision (4), um den Wert später bei Update-Anfragen nutzen zu können.

Paging

a. Paging auf der Liste out1:

Um auf der Liste out1 (“Redaktionelle Ausgangsliste” im FlypSte-Backend) zu pagen, nutzen Sie die next-Angabe aus dem vorangehenden Aufruf (im Beispiel hier 2737), eine Seitengröße von 30 sowie den commit aus der letzten Response, um die nächsten 30 Posts abzurufen:

https://flypsite.appspot.com/v1/{{token}}/s/out1/2737/30/desc.json?87d0113b-07fe-4dcb-b7bc-615ae61fa831

Response:

{
"layout":null,
"next":2466,
"_nitems":30,
"_start":2737,
"size":30,
"stream":"out1",
"more":true,
"style":null,
"updates":[]
}

updates wird wieder eine Sammlung von Posts enthalten; next dient zum weiter-pagen.

b. Paging auf anderen Streams:

Bestimmen Sie beim Einlesen der initial.json den niedrigsten index-Wert für einen Stream. Nutzen Sie diesen als Ausgangspunkt für Ihren Abruf von desc.json.

Updates

Um die JSON-API für Updates zu nutzen, rufen Sie mit einer Frequenz von maximal einem Abruf pro 60 Sekunden die carrier.json vereindeutigt ab:

https://flypsite.appspot.com/v1/{{token}}/carrier.json?8456829346

Response:

{
"revision":5,
"commit":"403c3b37-d33c-47d7-859f-c57beba31e4f",
"eventid":3431
}

Bestimmen Sie anhand der hier erhaltenen revision die nötigen Aufrufe: Erhöhen Sie die beim initialen oder vorangehenden Aufruf erhaltene revision um 1 und berechnen Sie {{rev}} wie folgt:

("0000" + (abzurufenderev % 256).toString(16)).substr(-4)

Nutzen Sie commit, um den folgenden Aufruf zu parametrisieren:

`https://flypsite.appspot.com/v1/{{token}}/u/{{rev}}/update.json?{{commit}}

in diesem Fall:

https://flypsite.appspot.com/v1/{{token}}/u/0005/update.json?403c3b37-d33c-47d7-859f-c57beba31e4f

Response:

{
"eventid":3431,
"more":false,
"commit":"5ef19fe6-a33b-4c7d-854b-c0bca5510a9b",
"updates":[],
"revision":5
}

Neue Posts, Aktualisierungen und Löschungen

action: "new" auf dem Envelope eines Updates zeichnet einen neuen Post aus, action: "delete" die Löschung und action: "update" die Modifikation eines vorhandenen Posts.