{ "version": "2.0", "xmlns": { "atom": "http://www.w3.org/2005/Atom", "content": "http://purl.org/rss/1.0/modules/content/", "georss": "http://www.georss.org/georss", "gml": "http://www.opengis.net/gml" }, "channel": { "title": "fboës - Der Blog | Artikel mit dem Tag \"API\"", "link": "https://journal.3960.org/", "description": "Programmierung, Luft- & Raumfahrt, Kurioses: Der Blog von und mit Frank Boës.", "language": "de-DE", "copyright": "© 2008-2023 Creative Commons BY", "atom_link": { "href": "https://journal.3960.org/tagged/api/rss.json", "rel": "self", "type": "application/rss+json" }, "lastBuildDate": "Fri, 22 Mar 2024 18:00:20 +0100", "atom_updated": "2024-03-22T18:00:20+01:00", "generator": "blogophon", "image": { "url": "https://cdn.3960.org/images/tile-128x128.png", "title": "fboës - Der Blog", "link": "https://journal.3960.org/" }, "items": [ { "title": "Das Wettergerät für Aerofly FS2", "description": "
Was Anfang des Jahres als kleine Idee begonnen hatte, ist inzwischen in einem einigermaßen komplexen Projekt gemündet: Ich wollte das Wetter in meinem Lieblings-Flugsimulator Aerofly FS2 verbessern.
", "content_encoded": "Was Anfang des Jahres als kleine Idee begonnen hatte, ist inzwischen in einem einigermaßen komplexen Projekt gemündet: Ich wollte das Wetter in meinem Lieblings-Flugsimulator Aerofly FS2 verbessern.
\n\nAerofly FS2 ist noch weit entfernt von der Tiefe und Komplexität von X-Plane oder auch Prepar3D. Darum hatte ich mir zwischenzeitlich X-Plane angeschaut, war aber inzwischen bereits sehr verwöhnt von der Performance und Unkompliziertheit von Aerofly FS2. Gerade die Unterstützung für Virtual Reality gefiel mir in AFS2 einfach besser, so dass ich X-Plane inzwischen wieder in den Hangar gerollt hatte.
\nNach meiner Rückkehr zu AFS2 vermisste ich nun aber doch ein paar Features:
\nWährend die lebendig wirkende Umwelt (in Form von Autos und Schiffen) gerade durch das Aerofly Life Project angegangen wird, habe ich mir also das Wetter vorgenommen.
\nTatsächlich existiert in X-Plane eine Idee, die in Aerofly FS2 ebenfalls funktioniert: Jeder größere Flughafen auf diesem Planeten veröffentlicht in relativ kurzen Abständen seinen aktuellen Wetterbericht in Form eines METAR. Dieser Wetterbericht ist nicht nur sehr verdichtet, sondern auch mit etwas Geschick maschinenlesbar.
\nKEYW 261153Z 36005KT 10SM FEW012 23/23 A3004 RMK AO2 SLP172 T02330217 10233 20222 53012\n
\nDarüber hinaus gibt es viele Anlaufstellen, die METARs über eine HTTP-Schnittstelle zur Verfügung stellen. Die Quelle war also gefunden.
\nGleichzeitig hatte ich in der Hauptkonfigurationsdatei main.mcf
von AFS2 entdeckt, dass die Wetterdaten darin gespeichert wurden. Zu meiner Überraschung fanden sich dort sogar Schalter, die in der Simulation selber gar nicht konfigurierbar waren. Mit ein paar wenigen Experimenten konnte ich nachweisen, dass Veränderungen in der main.mcf
tatsächlich in AFS2 übernommen wurden – hier war also mein Ziel.
Die Aufgabe war jetzt also klar erkennbar:
\nmain.mcf
.Als Webprogrammierer habe ich mich für das Projekt an eine Sprache gehalten, die ich gut kannte: JavaScript, bzw. NodeJS.
\nHier zahlte sich vor allen Dingen aus, dass ich privat sehr gerne test-getrieben entwickele, da das Format von METARs doch einige Überraschungen parat hatte. Unzählige Tests später hatte ich dann aber einen METAR-Parser, der mit vielen Fallstricken der METAR-Angaben umgehen konnte.
\nSchon nach einem Monat kopierte das Kommandozeilen-Tool fröhlich METAR-Daten in Aerofly FS2. Das ganze Projekt veröffentliche ich als „Aerofly-Weather“ bzw. „AeroWX“ bei NPM.
\nSchon bald fiel mir aber auf, dass ich zu kurz gesprungen war: Einerseits erforderte mein Programm die Installation von NodeJS – andererseits war es ein Kommandozeilenprogramm, mit entsprechend wenig ansprechender Präsentation.
\nEs musste also eine bedienbare Desktop-Applikation her. Da ich als Webprogrammierer mit dieser Welt bisher nur sehr wenig Erfahrung hatte, fand ich zum Glück eine Lösung genau nach meinem Geschmack: Electron.
\nMit Electron konnte ich nicht nur meine NodeJS-Programmierung direkt weiterverwenden, das GUI meiner Applikation konnte mit HTML, CSS und JavaScript gebaut werden – Sprachen, mit denen ich jeden Tag arbeite. So konnte mit relativ moderatem Aufwand nach einem Monat eine Desktop-Applikation gebaut werden. Diese wurden mit dem Electron-Builder zu einer eigenständigen EXE-Datei kompiliert und ließ sich dann als „Aerofly-Weather“ bzw. „AeroWX“ bei Github herunterladen.
\nAber auch hier nagte die Unzufriedenheit an mir: Diese Applikation hatte als ZIP gepackt eine Größe von über 60MB, und auch die Ausführung dieses Programms verschlang Unmengen an RAM. Für eine so kleine Applikation war dies kaum zu rechtfertigen.
\nDurch einen Tipp aus der Aerofly-Community hatte man mir einen neuen Floh ins Ohr gesetzt: Eine Umsetzung in C++. Damit könnte ich den Nutzer von der Last befreien, entweder NodeJS zu installieren oder sich eine immens große Electron-App herunterzuladen. Nach ein bisschen Recherche und Interviews mit befreundeten Programmierern stürzte ich mich erneut ins Unterholz, um das Projekt nochmals zu bauen – nur diesmal in C++.
\nPraktischer Nebeneffekt war, dass ich alle funktionalen Überlegungen bereits in NodeJS gelöst hatte. In meiner Vorstellung konnte ich mich also ganz auf das Umschreiben meines Projekts von JavaScript auf C++ konzentrieren. Tatsächlich waren ein Großteil der Ideen in C++ reproduzierbar, wenn auch die strenge Typisierung (als PHP- und JavaScript-Programmierer eine ganz neue Erfahrung) und die nun notwendige IDE (Microsoft Visual Studio) doch zuerst eine erhebliche Hürde darstellte.
\nNichtsdestotrotz konnte nach knapp zwei Wochen das ursprüngliche Projekt als eigenständig ausführbare Applikation umgesetzt werden. Die Ausgabe auf der Kommandozeile war beinahe identisch – die Größe der eigentlichen Applikation aber deutlich kompakter, und vor allen Dingen die Installation von NodeJS nicht mehr erforderlich. Mit einem einfachen Deployment-Workflow konnte die Applikation als „Aerofly Wettergerät“ bei Github bereitgestellt werden.
\nDas Aerofly Wettergerät brauchte nun ebenfalls einen feschen Desktop-Aufsatz. Hier hatte ich zuerst Sciter ausprobiert – ähnlich wie Electron hätte man HTML und CSS für die Gestaltung des Frontends verwenden können. Nach einigen Tests erwies sich aber Sciter für meine Belange als wenig geeignet. Stattdessen war der Tipp eines Kollegen goldrichtig: WxWidgets erlaubte mit überschaubarem Aufwand von zwei weiteren Wochen, eine native Applikation im Look & Feel des Betriebssystems zu erstellen.
\nDie so entstandene Desktop-Applikation wurde ebenfalls im Paket vom „Aerofly Wettergerät“ bei Github bereitgestellt, so dass sowohl die Kommandozeilen- als auch die Desktop-Version nicht nur die selben Sourcen haben, sondern auch im selben Installationspaket geliefert werden. Die Download-Größe liegt unter einem Zehntel des ursprünglichen NodeJS-Paketes, und auch der Fußabdruck im RAM ist um Größenordnungen kleiner – wenn auch die Ausgabe nun etwas schlichter wirkt.
\nBis jetzt verbleibt ein Wehrmutstropfen bei dem Projekt: Das Wetter kann nur außerhalb der Simulation heruntergeladen und eingestellt werden. Damit bleiben folgende Fälle außen vor:
\nMeine Überlegungen dazu waren, mit dem von IPACS angebotenen SDK eine eigene DLL zu bauen, die alle zehn Minuten den nächstgelegenen Flughafen sucht, das Wetter herunterlädt und dann in die laufende Simulation importiert. Da für diese Idee die Schnittstellen in die Simulation aber aktuell nicht ausreichend dokumentiert sind bzw. auch nicht existieren, liegt das Projekt erstmal auf unbestimmte Zeit auf Eis.
", "link": "https://journal.3960.org/posts/2019-03-27-wettergeraet-fuer-aerofly-fs2/", "pubDate": "Wed, 27 Mar 2019 19:32:27 +0100", "atom_published": "2019-03-27T19:32:27+01:00", "atom_updated": "2020-02-11T08:52:46+01:00", "guid": "user/posts/2019-03-27-wettergeraet-fuer-aerofly-fs2/index.md", "author": "info@3960.org (Frank Boës)", "categories": [ "Aerofly FS2", "Fliegerei", "API", "Für Tumblr", "Programmierung", "Simulation", "Spiel" ] }, { "title": "PWA in 5 Minuten", "description": "Progressive Web Apps (oder kurz: „PWA“) gibt es schon länger – aber erst vor Kurzem habe ich begriffen, wie gering der Aufwand ist, eine beliebige Website schnell in eine PWA zu verwandeln.
", "content_encoded": "Progressive Web Apps (oder kurz: „PWA“) gibt es schon länger – aber erst vor Kurzem habe ich begriffen, wie gering der Aufwand ist, eine beliebige Website schnell in eine PWA zu verwandeln.
\n\nPWAs erlauben es euch, eure Website / Web App mit folgenden Eigenschaften auszustatten:
\nDiese beiden Fähigkeiten kombiniert erlauben es mit etwas Kreativität, Apps zu schreiben, die sowohl im Browser als auch offline auf einem Telefon funktionieren. Schon vor geraumer Zeit hatte ich ein paar schlaue Ideen für den sinnvollen Einsatz von PWAs gesammelt. Vor allen Dingen die geringe Installationsgröße und die Installation ohne App Store machen diese Technologie für Gelegenheits-Apps sehr interessant.
\nIm Endeffekt besteht eine komplette PWA in der einfachsten Ausführung aus drei Teilen:
\nmanifest.json
, in der der Name und die Icons eurer App beschrieben werden (siehe Doku von MDN und Google),sw.js
, der die Offline-Strategie eurer App beschreibt (siehe Doku von MDN und Google),manifest.json
und die sw.js
dem Browser bekannt macht.Das ganze Setup ist so einfach, dass ich die praktische Umsetzung bzw. Kopiervorlagen für eine generische PWA in einem kleinen PWA-Starter-Kit zusammengefasst habe. Hier findet ihr Template-Schnipsel zum Kopieren, und bei Bedarf sogar ein kleines Tool, was diese Template-Schnipsel mit euren Daten ausfüllt.
\nBeim Bau des Service Workers kann man auch von PWA Builder komplexere Beispiele herunterladen, oder mit der Google Workbox sehr komfortabel Offline-Strategien programmieren.
\nNatürlich berührt man mit dieser Methode nur einen Teil der Möglichkeiten einer PWA. Gleichzeitig habt ihr so einen pragmatischen Start in das Thema „PWA“.
\nOb eure PWA funktioniert könnt ihr in zwei Browsern ganz einfach testen:
\nF12
), öffnet den Tab „Audits“ und startet dort einen Audit.Bei PWA.rocks gibt es eine größere Liste an schönen PWAs. Ich persönlich habe in den versprochenen fünf Minuten ein altes Uhren-Projekt von mir in eine PWA verwandelt.
\nDie Integration einer PWA in eine bereits existierende Website ist äußerst unaufwändig, und bringt für euch und eure Besucher viele Vorteile.
", "link": "https://journal.3960.org/posts/2018-10-19-pwa-5-minuten/", "pubDate": "Fri, 19 Oct 2018 19:53:09 +0200", "atom_published": "2018-10-19T19:53:09+02:00", "atom_updated": "2019-03-26T13:54:58+01:00", "guid": "user/posts/2018-10-19-pwa-5-minuten/index.md", "author": "info@3960.org (Frank Boës)", "categories": [ "Für Tumblr", "Programmierung", "API", "Webdevelop" ] }, { "title": "HTML-Input für Koordinaten", "description": "Das HTML5 <input>
-Element mit seinen praktischen neuen Typen wie z.B. number
, date
oder tel
erleichtert Frontend-HTML-Entwicklern viel Hebearbeit. Neben einer automatischen Validierung gibt es kleinen Helferlein bei der Eingabe (z.B. einen Kalender oder eine passende Tastatur). Einen Eingabetyp vermisse ich aber immer wieder.
Das HTML5 <input>
-Element mit seinen praktischen neuen Typen wie z.B. number
, date
oder tel
erleichtert Frontend-HTML-Entwicklern viel Hebearbeit. Neben einer automatischen Validierung gibt es kleinen Helferlein bei der Eingabe (z.B. einen Kalender oder eine passende Tastatur). Einen Eingabetyp vermisse ich aber immer wieder.
Viele Web-Applikationen benötigen heutzutage die Eingabe eines Ortes – oder genauer gesagt: Von Geo-Koordinaten. Die Suche nach einem Hotel, einer Tankstelle oder einer Bus-Haltestelle in der Nähe eines bestimmten Ortes erfordert meist die händische Eingabe einer Adresse. Der Prozess für die Eingabe eines Ortes ist i.d.R. wie folgt:
\nAlternativ oder zusätzlich gibt es ein Javascript-API zur Geo-Lokalisierung, deren Einbindung man als Server-Anbieter aber zuerst programmieren muss.
\nSo oder so hat der Prozess entweder mit einiger Kommunikation zwischen Browser, Server und einer GEO-API zu tun, oder aber mit Javascript-Programmierung. Wäre es nicht schön, wenn HTML direkt ein Eingabefeld für genau diese Aufgabe anbietet?
\n\n
In meiner Vorstellung benötigen wir einfach nur einen neuen HTML5-<input>
-Typ zur Erfassung und Übermittlung von Geo-Koordinaten. Dieser Typ könnte z.B. coordinates
heißen. Beim Anklicken dieses Eingabefelds taucht beim Nutzer im Browser ein Widget für die Auswahl der Koordinaten auf. Das könnte wie folgt funktionieren:
Bei den letzten beiden Methoden könnte man auf Karten- und Koordinaten-Daten zugreifen, die von vorhergehenden Operationen zwischengespeichert wurden – damit entfällt die Notwendigkeit, noch eine weitere Schnittstelle zu bemühen.
\nDer Browser wiederum erhält dann die Koordinaten und übermittelt diese an den Server, so dass er keinerlei Umwandlung mehr durchführen muss.
\nIm HTML könnte dieses Eingabefeld wie folgt aussehen:
\n<input name="coordinates" type="coordinates" />\n<input name="coordinates" type="coordinates" step="0.001" value="53.246, 10.412" />\n<input name="coordinates" type="coordinates" min="-90, -180" max="90, 180" />\n
\nDie Präzision der Geo-Koordinaten kann man dabei via step
-Attribut einstellen (analog zu type=„number“
). Mit min
- und max
-Attribut könnte man sogar den erlaubten Koordinatenraum eingrenzen.
Wie auch immer das kleine Helferlein zur Auswahl der Koordinaten aussieht, es gibt einfach dezimale Breiten- und Längengrad-Angaben im üblichen WGS84-System zurück, separiert mit einem Komma und einem Leerzeichen. Das sieht dann zum Beispiel so aus: 53.246, 10.412
.
Das Muster für die Rückgabe könnte man auch mit dem pattern
-Attribut beschreiben, so dass auch aktuelle HTML5-Browser schon das korrekte Format erzwingen würden:
<input name="coordinates" type="coordinates" pattern="-?\\d{1,2}(?:\\.\\d+)?, -?1?\\d{1,2}(?:\\.\\d+)?" />\n
\nWie üblich bei neuen <input>
-Typen würden alte Browser einfach ein ganz normales Eingabefeld anzeigen. Mit Javascript kann man dann ein Polyfill dafür erstellen, dass für alle unkundigen Browser ein alternatives Eingabe-Widget zur Verfügung stellt – ein Widget, dass man aktuell ohnehin bauen müsste.
Schon lange hat mich die Idee umgetrieben, Newsfeeds statt mit dem etwas sperrigen XML (wie bei RSS und ATOM) lieber in JSON auszuliefern.
\nNun hat Manton Reece zusammen mit Brent Simmons ebenfalls die Idee eines JSON-Newsfeeds aufgegriffen, und einen eigenen Standard entwickelt: JSON Feed.
", "content_encoded": "Schon lange hat mich die Idee umgetrieben, Newsfeeds statt mit dem etwas sperrigen XML (wie bei RSS und ATOM) lieber in JSON auszuliefern.
\nNun hat Manton Reece zusammen mit Brent Simmons ebenfalls die Idee eines JSON-Newsfeeds aufgegriffen, und einen eigenen Standard entwickelt: JSON Feed.
\n\nJSON hat mehrere Vorteile gegenüber XML. Vorneweg ist das Parsing deutlich einfacher, da JSON Sprachkonstrukte abbildet, die es in fast jeder Programmiersprache gibt: Objekte, Arrays, Strings und Zahlen. XML dagegen benötigt immer eine Form von komplexer Übersetzungsvorschrift, um Knoten, Attribute und sich wiederholende Tag-Namen als Konstrukt abzubilden.
\nIn PHP ist das Lesen von JSON so einfach wie der Aufruf von json_decode()
; in Javascript übernimmt JSON.parse()
diese Aufgabe; in beiden Fällen steht danach eine schon aus dem JSON ablesbare Struktur aus Objekten, Arrays, Strings und Zahlen zu Verfügung.
Da JSON direkt durch Javascript interpretiert werden kann, kann es auch direkt vom Browser ausgeführt werden. Es entfällt die Notwendigkeit, zum Parsen des Newsfeeds auf serverseitige Skripte zurückgreifen zu müssen.
\nDie Idee, einen Newsfeeds mit JSON auszugeben, gab es schon öfter:
\nJSON Feed wird u.a. von Mantons Service micro.blog unterstützt, zudem gibt es Plugins für Wordpress, Jekyll, Movable Type und das Craft CMS. Weitere Plugins für JSON Feed entstehen in schneller Folge.
\nDa ich persönlich sehr an JSON als Schnittstellenformat glaube, habe ich schnell für das Blogopohon eine Option hinzugefügt, so dass alle Blogophon-Blogs auch via JSON-Feed abrufbar sind. Ein Beispiel für den JSON Feed des Blogohons findet sich hier.
\nDer JSON Feed Standard erlaubt von vorneherein Erweiterungen. Diese sind dann zwar nicht standardisiert, können aber benötigte Funktionalität bereitstellen, ohne zu Namensraum-Kollisionen mit späteren Erweiterungen des Standards zu führen. Dies Erweiterungen funktionieren wie folgt:
\n\nNatürlich habe ich auch gleich kleine Erweiterung für mich eingebaut:
\nIn item
existiert ein optionales GeoJSON-Geometry-Objekt, mit dem sich Koordinaten bzw. geografische Objekte übertragen lassen:
"_geo": {\n "about": "http://geojson.org/#GeometryObject",\n "type": "Point",\n "coordinates": [125.6, 10.1]\n}\n
\nZudem erlaubt mir die Verwendung des RSS-Tags, die vielfältigen Eigenschaften von RSS auch in JSON Feed zu verwenden:
\n"_rss": {\n "about": "http://cyber.harvard.edu/rss/rss.html",\n "copyright": "© 2008-2018 Creative Commons BY"\n}\n
\nÜber die Sinnhaftigkeit von Newsfeeds wurde bereits hinlänglich nachgedacht.
\nJSON Feed sieht wie ein würdiger Nachfolger für RSS und ATOM aus, der an Stelle von XML das leichtgewichtige JSON verwendet. Aktuell hat JSON Feed noch nicht die selben Möglichkeiten Daten zu transportieren, und auch die Unterstützung von Feed-Readern muss erst wachsen. Für interne Schnittstellen ist dies aber allemal ein sehr guter Standard, der sich augenscheinlich auch inzwischen wie ein Lauffeuer in der Blogosphäre ausdehnt.
\nUpdate 2020–11: Da inzwischen JSON Feed Version 1.1 veröffentlicht wurde, wurde der Artikel angepasst. U.a. wurden ursprünglich als Erweiterung konzipierte Angaben für die Sprache eines Artikels jetzt direkt im Standard gelöst.
", "link": "https://journal.3960.org/posts/2017-05-19-json-feed-endlich-standard-r-newsfeeds-mit-json/", "pubDate": "Fri, 19 May 2017 19:00:00 +0200", "atom_published": "2017-05-19T19:00:00+02:00", "atom_updated": "2020-11-18T10:34:07+01:00", "guid": "user/posts/2017-05-19-json-feed-endlich-standard-r-newsfeeds-mit-json.md", "author": "info@3960.org (Frank Boës)", "categories": [ "Blog", "Programmierung", "CMS", "API", "Technologie" ] }, { "title": "Wie zieht man Slacks Slash-Commands in Rocket.Chat?", "description": "Wenn man gerade erst ein einfaches Slash-Command für Slack gebaut hat, lässt es sich mit überschaubaren Aufwand auch für Rocket.Chat verwenden. Die folgende Schritte führen zum Ziel:
", "content_encoded": "Wenn man gerade erst ein einfaches Slash-Command für Slack gebaut hat, lässt es sich mit überschaubaren Aufwand auch für Rocket.Chat verwenden. Die folgende Schritte führen zum Ziel:
\n\n/
./command
an @command
schreiben, und den Bot als Gesprächspartner verwenden.class Script {\n prepare_outgoing_request({ request }) {\n // request.params {object}\n // request.method {string}\n // request.url {string}\n // request.auth {string}\n // request.headers {object}\n // request.data.token {string}\n // request.data.channel_id {string}\n // request.data.channel_name {string}\n // request.data.timestamp {date}\n // request.data.user_id {string}\n // request.data.user_name {string}\n // request.data.text {string}\n // request.data.trigger_word {string}\n\n if (new RegExp('^[\\\\/\\\\+@]?(' + request.data.trigger_word + ')(\\\\s|$)').test(request.data.text)) {\n request.params2 = Object.keys(request.data).map(function (key) { \n return key + '=' + encodeURIComponent(request.data[key]); \n });\n request.params2.push('text=' + encodeURIComponent(request.data.text.replace(/^\\S+(\\s|$)/, '')));\n request.params2.push('command=' + encodeURIComponent('/' + request.data.trigger_word));\n request.params2.push('client=' + encodeURIComponent('rocket'));\n request.url += '?' + request.params2.join('&');\n return request;\n }\n }\n\n process_outgoing_response({ request, response }) {\n // response.error {object}\n // response.status_code {integer}\n // response.content {object}\n // response.content_raw {string/object}\n // response.headers {object}\n\n return response;\n }\n}\n
\nMit diesem Script werden die Request-Parameter soweit umgeformt, dass sie den von Slack bekannten Parametern entsprechen. Die Response wiederum ist im Groben und Ganzen kompatibel mit Rocket.Chat.
", "link": "https://journal.3960.org/posts/2017-05-07-wie-zieht-man-slacks-slash-commands-rocket-chat/", "pubDate": "Sun, 07 May 2017 19:00:00 +0200", "atom_published": "2017-05-07T19:00:00+02:00", "atom_updated": "2019-03-26T13:54:25+01:00", "guid": "user/posts/2017-05-07-wie-zieht-man-slacks-slash-commands-rocket-chat.md", "author": "info@3960.org (Frank Boës)", "categories": [ "Programmierung", "API", "Für Tumblr" ] }, { "title": "Wie hoch ist der Aufwand bei der Einbindung von Schnittstellen?", "description": "Die Anbindung an APIs hat teilweise erheblich von einander abweichende Aufwände. Was sind die Warnzeichen, dass der Aufwand für eine Schnittstelle deutlich höher werden kann?
", "content_encoded": "Die Anbindung an APIs hat teilweise erheblich von einander abweichende Aufwände. Was sind die Warnzeichen, dass der Aufwand für eine Schnittstelle deutlich höher werden kann?
\n\nProbleme und Stolpersteine beim Einbinden von Schnittstellen kann man im Vorfeld zumeist schon erahnen. Jede gute Schnittstelle verfügt über drei Qualitätsmerkmale:
\nIm Idealfall existiert auch noch ein Ansprechpartner. Wenn eine Schnittstelle keine Dokumentation besitzt, muss sie über einen Ansprechpartner verfügen. Die Aussage „Die Schnittstelle ist selbstdokumentierend“ ist übrigens ein Warnsignal, dass Probleme und Aufwände zu erwarten sind.
\nIm Vorfeld sind folgende Fragen in Bezug auf eine Schnittstellen-Dokumentation wichtig:
\nDie Dokumentation muss dann folgende Fragen beantworten:
\nFür jede Entitätentyp einzeln zu beantwortende Fragen:
\nEin fantastisches Beispiel für eine REST-API-Dokumentation existiert bei der Twitter API-Dokumentation.
\nUnd wenn eine API noch keine Dokumentation hat, kann man mittels Swagger eine schön saubere und gleichzeitig testbare Dokumentation aufbauen.
", "link": "https://journal.3960.org/posts/2017-05-06-wie-hoch-der-aufwand-bei-schnittstellen/", "pubDate": "Sat, 06 May 2017 19:00:00 +0200", "atom_published": "2017-05-06T19:00:00+02:00", "atom_updated": "2020-01-20T17:17:37+01:00", "guid": "user/posts/2017-05-06-wie-hoch-der-aufwand-bei-schnittstellen.md", "author": "info@3960.org (Frank Boës)", "categories": [ "Programmierung", "API", "Für Tumblr" ] }, { "title": "Slack-API als JSON-RSS-Ersatz", "description": "\nSchon vor geraumer Zeit hatte ich mich mit der Idee beschäftigt, wie man Syndikation nicht mit dem im Parsing etwas aufwändigen XML, sondern eher mit JSON lösen kann. Meine Idee damals hieß JSON-RSS, und war analog zu der Struktur von RSS aufgebaut. Tatsächlich hat zufälligerweise Slack ein Format entwickelt, was analog zu JSON-RSS Syndikation via JSON löst – mit einem zusätzlichen Nebeneffekt.
", "content_encoded": "\nSchon vor geraumer Zeit hatte ich mich mit der Idee beschäftigt, wie man Syndikation nicht mit dem im Parsing etwas aufwändigen XML, sondern eher mit JSON lösen kann. Meine Idee damals hieß JSON-RSS, und war analog zu der Struktur von RSS aufgebaut. Tatsächlich hat zufälligerweise Slack ein Format entwickelt, was analog zu JSON-RSS Syndikation via JSON löst – mit einem zusätzlichen Nebeneffekt.
\n\nDie Slack Message-API beschreibt dabei eine Liste von Einträgen (attachement
genannt), in der man URLs, Titel, Beschreibungstexte und Veröffentlichungsdatum in JSON transportieren kann. Dazu liefern sie den praktischen Slack Message-Builder, mit dem man sein generiertes JSON auch direkt testen kann. Damit entspricht das Slack-JSON inhaltlich im Groben und Ganzen RSS bzw. ATOM.
{\n "response_type": "ephemeral",\n "text": "fboës - Der Blog | Startseite", // <title>\n "attachments": [\n { // <item>\n "title": "Slack-API als JSON-RSS-Ersatz", // <title>\n "title_link": "https://journal.3960.org/posts/slack-api-json-rss-ersatz/", // <link>\n "text": "Schon vor geraumer Zeit hatte ich mich mit der Idee beschäftigt…", // <description>\n "author_name": "Frank Boës", // <author>\n "ts": 1491245995 // <pubdate>\n "thumb_url": "https://journal.3960.org/posts/slack-api-json-rss-ersatz/slack.jpg", // <enclosure>\n "fallback": "Slack-API als JSON-RSS-Ersatz - https://journal.3960.org/posts/slack-api-json-rss-ersatz/", // <description> fallback\n "footer": "fboës - Der Blog", // <title> of feed\n }\n ]\n}\n
\nNun hatte Slack dieses Format eigentlich gar nicht für Syndikation entwickelt, sondern als Datenquelle für Slack-Bots. Denn innerhalb des Slack-Messengers kann dieses JSON direkt ausgegeben werden.
\nDarum kann man das JSON nicht nur für selbst entwickelte Schnittstellen verwenden, sondern auch mittels Slack Slash Command zu seinem eigenen Slack-Kanal hinzufügen. So könnte man sich mit einem Slack-Kommando wie /news
die aktuellsten Artikel einer beliebigen Seite anzeigen lassen.
Dementsprechend produziert das Blogophon nun auch eine slack.json
, die man mittels Slash Command in Slack einbinden kann.
So ziemlicher jeder Artikel, den man in ein CMS einträgt, verfügt über drei Eigenschaften, mit denen sich ähnliche Artikel finden lassen. Bei einer geschickten Verknüpfung dieser drei Eigenschaften bzw. Achsen kann man so als Redakteur dem Leser des Artikels sehr einfach verwandte Artikel anzeigen.
", "content_encoded": "So ziemlicher jeder Artikel, den man in ein CMS einträgt, verfügt über drei Eigenschaften, mit denen sich ähnliche Artikel finden lassen. Bei einer geschickten Verknüpfung dieser drei Eigenschaften bzw. Achsen kann man so als Redakteur dem Leser des Artikels sehr einfach verwandte Artikel anzeigen.
\n\nDiese drei Achsen sind:
\nÜber diese drei Achsen kann man Artikel finden bzw. miteinander vernetzen. Es ist also möglich, Artikel zu finden, die in inhaltlicher, zeitlicher oder räumlicher Nähe zueinander liegen. Auch ist es möglich, über diese Eigenschaften den Leser suchen zu gestatten, so dass er z.B. Einträge in einem bestimmten Zeitraum oder in der Nähe eines bestimmten Ortes finden kann.
\nÜbrigens können nicht nur Artikel, sondern auch Bilder und Videos auf diese Weise ausgezeichnet werden.
\nBesonders spannend werden diese drei Achsen bei besonderen publizistischen Formaten, wie z.B. Nachrichten, Chronologien, Journalen oder Tagebüchern. Hier könnte man z.B. eine zeitliche und/oder räumliche Entwicklung nachvollziehen.
\nZur Unterstützung oder als Ersatz für Freitextsuchen eignen sich die drei Achsen sowieso. Sie können z.B. als erweiterte Suche den Zugriff auf Inhalte erlauben.
\nGleichzeitig kann die Suche auch als REST-API zum Auffinden von Inhalten von extern wie intern verwendet werden. Dabei kann die API auch unterschiedliche Ausgabeformate (s.u.) zurückgeben.
\n…bedeutet das nur, dass man jeden Artikel mit Tags, einem Datum und Geo-Koordinaten ausstatten muss. Während die ersten beiden Dinge in fast jedem CMS einfach zu bewerkstelligen sind, ist letzteres möglicherweise etwas schwieriger. Im Notfall muss man ein Freitext-Meta-Daten-Feld dafür zweckentfremden, und die Geo-Koordinaten durch ein Online-Tool ermitteln.
\nDazu gibt es maschinenlesbare Formate, die je nach Achse einen Zugang ermöglichen:
\nDiese Formate erlauben u.a. auch die Verwendung der Daten in einem alternativen Darstellungs-Programm außerhalb des Browsers, wie z.B. Google Earth oder einer Kalender-App.
", "link": "https://journal.3960.org/posts/wie-finde-ich-aehnliche-artikel-einem-cms/", "pubDate": "Sun, 01 Jan 2017 19:45:27 +0100", "atom_published": "2017-01-01T19:45:27+01:00", "atom_updated": "2019-03-26T13:55:57+01:00", "guid": "user/posts/wie-finde-ich-aehnliche-artikel-einem-cms.md", "author": "info@3960.org (Frank Boës)", "categories": [ "CMS", "Blog", "Programmierung", "API", "Geografie" ] }, { "title": "RSS ist niemals tot", "description": "Immer und immer wieder musste sich RSS der Vorwurf gefallen lassen, das es tot sei. Tatsächlich beruhen solche Aussagen aber auf einem Missverständnis, wofür RSS verwendet werden sollte. Kurz gefasst: Eine Website ohne RSS-Newsfeed ist wie ein tolles Produkt ohne Marketing.
", "content_encoded": "Immer und immer wieder musste sich RSS der Vorwurf gefallen lassen, das es tot sei. Tatsächlich beruhen solche Aussagen aber auf einem Missverständnis, wofür RSS verwendet werden sollte. Kurz gefasst: Eine Website ohne RSS-Newsfeed ist wie ein tolles Produkt ohne Marketing.
\n\nNachdem vor geraumer Zeit z.B. Facebook seine Unterstützung für RSS beendete, und viele Newsreader-Dienste ihren Betrieb einstellten, wirkte es so, als ob RSS nicht mehr nötig sei. Tatsächlich hat RSS aber zwei sehr unterschiedliche Verwendungszwecke:
\nWährend der erste Einsatzzweck sich tatsächlich niemals so richtig durchgesetzt hat, lebt und prosperiert der zweite Zweck umso mehr.
\nRSS liefert eine strukturierte Liste von Einträgen, wobei jeder Eintrag einen Titel, eine Beschreibung und einen Link haben sollte. Optional kann für jeden Eintrag z.B. ein Veröffentlichungsdatum hinzugefügt werden.
\nRSS wird oft so missverstanden, dass es sich nur zum Transport von Artikeln eignet. Die RSS-Spezifikationen decken aber eigentlich alles ab, was man mit einem Titel, einem Beschreibungstext und einem Link verbreiten möchte. Und das beinhaltet
\nDa RSS wie alles in XML durch Namensräume erweiterbar ist, gibt es inzwischen für RSS auch sehr praktische RSS-Erweiterungen:
\nDamit sind selbst ungewöhnliche Anwendungsfälle durch standardisierte Spezifikationen bereits abgebildet.
\nSelbst mit all diesen Erweiterungen kann man immer noch die Validität eines RSS-Feeds überprüfen – eine nicht zu unterschätzende Hilfe, wenn man RSS als API versteht, und auf eine standardisierte Kommunikation angewiesen ist.
\nÜbrigens: RSS kann sich wie jede REST-API verhalten. Es liegt also in der Findigkeit des Programmierers des Newsfeeds, ob der RSS-Feed z.B. eine Zugangsbeschränkung hat, oder per Parametern die Auswahl der angezeigten Beiträge verändert werden kann.
\nDie Standardisierung erleichtert den Austausch von Daten zwischen heterogenen Umgebungen ungemein. Angefangen bei der Tatsache, dass RSS-Feeds als Sitemaps verwendet werden können, kann RSS von dem Betreiber einer Website dazu eingesetzt werden, um Artikel zu re-publizieren, d.h. seine Inhalte über weitere Kanäle zu verbreiten und seine Reichweite mit geringem Aufwand zu erhöhen.
\nMit RSS kann man z.B. die folgenden Kanäle aufwandsarm bespielen:
\niframe
-Widget auf die Seite kleben können. Analog zu einem Facebook- oder Twitter-Widget kann man sich so die aktuellsten Nachrichten von anderen Seiten holen.Der geneigte Leser einer Website muss also gar nicht selber verstehen, was RSS-Feeds sind, um sie doch implizit zu nutzen.
\nÜbrigens: In fast jedem CMS sollte es eine Möglichkeit geben, pro Ausgabekanal einen separaten RSS-Feed zu definieren. So kann der Redakteur z.B. über die Vergabe von Tags steuern, dass bestimmte Meldungen nur z.B. bei Facebook oder im Newsletter republiziert werden.
\nRSS besteht aus XML. Nun haben sich schon länger viele kluge Menschen für JSON als fettfreie Alternative zu XML ausgesprochen. Neben dem geringeren Aufwand beim Parsen der Daten spricht auch für JSON, dass Javascript die Daten direkt verwenden kann; so kann ein Browser direkt per AJAX JSON-Daten anzeigen.
\nIch persönlich hatte in 2011 über JSON-RSS nachgedacht, und 2012 beschäftige sich Dave Winer mit JSON-RSS. Tatsächlich gibt es seitdem verschiedene JSON-Experimente, die aber leider nie in einer Spezifikation mündeten.
\nDie Grundstruktur von JSON-RSS ist dabei überall identisch und eine einfach Übertragung der XML-Daten in JSON. Unterschiede bei der Implementation gibt es aber auch:
\nitem
, dann wieder items
.rss
-Property.So ist der JSON-RSS leider nicht wirklich so universell einsetzbar wie XML-RSS. Die JSON-Variante lohnt sich eher für lokale Spezialfälle, bei der alle Teilnehmer des Datenaustauschs vorher genau die Spezifikationen festgeklopft haben.
\nDieser Blog verwendet ein lebendes Beispiel für JSON-RSS, das analog zum regulären XML-RSS gebaut wird.
\nUpdate: Manton Reece und Brent Simmons haben inzwischen auch JSON Feed spezifiziert, um Syndikation via JSON zu lösen.
\nRSS sollte in jedem CMS vorhanden sein. Dabei ist nicht so sehr entscheidend, dass die Besucher der Seite auf RSS hingewiesen werden, sondern dass man RSS als Chance begreift, damit vielfältige Ausgabe-Kanäle ohne großen Aufwand zu bespielen. Bei der Verwendung eines validen RSS-Feeds erübrigt sich der Bau (und Test) von Konnektoren für ein proprietäres Daten-Austausch-Format.
", "link": "https://journal.3960.org/posts/rss-ist-niemals-tot/", "pubDate": "Fri, 30 Dec 2016 19:34:40 +0100", "atom_published": "2016-12-30T19:34:40+01:00", "atom_updated": "2019-03-26T13:55:27+01:00", "guid": "user/posts/rss-ist-niemals-tot.md", "author": "info@3960.org (Frank Boës)", "categories": [ "Blog", "CMS", "Programmierung", "API", "Technologie" ] } ] } }