Opencaching-API: Unterschied zwischen den Versionen

Aus Opencaching-Wiki
Zur Navigation springen Zur Suche springen
Zeile 24: Zeile 24:


=== Logtext-Format ===
=== Logtext-Format ===
Im Zuge der OKAPI-Anpassung an Opencaching.de wurde die Behandlung von Logtexten beim Hochladen von Logs (''submit'') geändert. Früher war das Format undefiniert – es konnte "plain text" oder HTML sein, und die Weiterverarbeitung hing von der jeweiligen Opencaching-Seite ab. Nun gibt es einen neuen Parameter ''comment_format'', mit dem das Format ausdrücklich angegeben werden kann und sollte.
Im Zuge der OKAPI-Anpassung an Opencaching.de wurde die Behandlung von Logtexten beim Hochladen von Logs (''submit'') geändert. Früher war das Format undefiniert – es konnte "plain text" oder HTML sein, und die Weiterverarbeitung hing von der jeweiligen Opencaching-Seite ab. Nun gibt es einen neuen Parameter [http://www.opencaching.pl/okapi/services/logs/submit.html#arg_comment_format comment_format], mit dem das Format ausdrücklich angegeben werden kann und sollte.


Auf keinen Fall sollte "plain text" ''ohne'' Angabe von ''comment_format=plaintext'' hochgeladen werden - der Text könnte verstümmelt werden.
Auf keinen Fall sollte "plain text" ''ohne'' Angabe von ''comment_format=plaintext'' hochgeladen werden - der Text könnte verstümmelt werden.
Zeile 33: Zeile 33:


===Lizenz-Disclaimer===
===Lizenz-Disclaimer===
Die OKAPI hängt standardmäßig einen Disclaimer an alle abgerufenen Cachebeschreibungen an, der den Datenlizenz-Anforderungen der jeweiligen Opencaching-Website entspricht. Über die neue Option [http://www.opencaching.de/okapi/services/caches/geocache.html#arg_attribution_append attribution_append=none] kann dies abgeschaltet werden. Stattdessen muss dann das Feld ''attribution_note'' angefordert und dessen Inhalt wiedergegeben bzw. mitgeliefert werden.
Die OKAPI hängt standardmäßig einen Disclaimer an alle abgerufenen Cachebeschreibungen an, der den Datenlizenz-Anforderungen der jeweiligen Opencaching-Website entspricht. Über die neue Option [http://www.opencaching.pl/okapi/services/caches/geocache.html#arg_attribution_append attribution_append=none] kann dies abgeschaltet werden. Stattdessen muss dann das Feld ''attribution_note'' angefordert und dessen Inhalt wiedergegeben bzw. mitgeliefert werden.


== Anmerkungen ==
== Anmerkungen ==

Version vom 4. April 2013, 21:47 Uhr

Die Opencaching-API (kurz: OKAPI) ist eine moderne Programmierschnittstelle, mit der Cache-, und Log- und Benutzerdaten von Opencaching-Seiten abgerufen werden können. Außerdem ist das Hochladen von Logs möglich. Dadurch lassen sich z.B. Smartphone-Apps mit Field-Logging-Funktion anbieten. Auch das Replizieren einer kompletten Opencaching-Datenbank ist möglich.

Weitere Funktionen sind das Beobachten und Ignorieren vom Caches; dabei wird auf die entsprechenden Listen im Benutzerprofil zugegriffen.

Die OKAPI ist inzwischen bei den Opencaching-Länderseiten in Polen, den USA, Großbritannien und den Niederlanden verfügbar. Eine Bereitstellung auf Opencaching.de[1] ist in Arbeit. Alternativ kann hier auch die weniger leistungsfähige XML-Schnittstelle genutzt werden.

Funktionsweise

Die OKAPI stellt verschiedene Webservices zur Verfügung, die Daten wahlweise im JSON- oder XML-Format liefern. Außerdem ist der Download von Cachedaten im GPX-Format möglich. Eine Beschreibung aller angebotenen Funktionen gibt es auf opencaching.pl/okapi.

Entwicklung

Die OKAPI wurde vom dem polnischen Geocacher Wojciech Rygielski (Wrygiel) entwickelt, der auch für die Weiterführung des Projekts verantwortlich ist. Die Entwicklung wird zentral auf Google Code koordiniert; von dort werden Code-Updates auf die einzelnen Länderseiten verteilt.

Einschränkungen

Gegenüber der üblichen Opencaching.de-Funktionalität hat die OKAPI einige Einschränkungen:

  • Eventcaches können nicht geloggt werden (in Arbeit)
  • es können keine Logbilder hochgeladen werden
  • Attribute werden bislang nicht als eigene Datenfelder, sondern nur als Textanhang in der Cachebeschreibung mitgeliefert, auch in GPX-Dateien. (in Arbeit)

Außerdem sind gespeicherte Suchen aus dem Benutzerprofil nicht nutzbar. Dies ist technisch schwer zu realisieren und wird vermutlich nicht eingebaut. OKAPI-Anwendungen können dieses Feature mittels OKAPI-Suchfunktionen nachbilden.

Anpassung bestehender OKAPI-Clients an Opencaching.de

Grundsätzlich sind alle bestehenden OKAPI-Anwendungen auch mit Opencaching.de funktionsfähig. Die Beachtung der folgenden Punkte kann aber hilfreich sein:

Logtext-Format

Im Zuge der OKAPI-Anpassung an Opencaching.de wurde die Behandlung von Logtexten beim Hochladen von Logs (submit) geändert. Früher war das Format undefiniert – es konnte "plain text" oder HTML sein, und die Weiterverarbeitung hing von der jeweiligen Opencaching-Seite ab. Nun gibt es einen neuen Parameter comment_format, mit dem das Format ausdrücklich angegeben werden kann und sollte.

Auf keinen Fall sollte "plain text" ohne Angabe von comment_format=plaintext hochgeladen werden - der Text könnte verstümmelt werden.

Unabhängig hiervon ist zu beachten, dass die Software unerlaubte HTML-Tags aus hochgeladenen Logtexten entfernt.

weitere Informationen zum OKAPI-Log-Format

Lizenz-Disclaimer

Die OKAPI hängt standardmäßig einen Disclaimer an alle abgerufenen Cachebeschreibungen an, der den Datenlizenz-Anforderungen der jeweiligen Opencaching-Website entspricht. Über die neue Option attribution_append=none kann dies abgeschaltet werden. Stattdessen muss dann das Feld attribution_note angefordert und dessen Inhalt wiedergegeben bzw. mitgeliefert werden.

Anmerkungen

  1. Opencaching.de schließt auch die italienische Seite Opencaching.it und die spanische Opencachingspain.es mit ein; alle laufen auf dem gleichen Server.