PageFormant API Version 3

Transkript

1 PageFormant API Version 3 1 Dokument-Historie Dokumenten-Version API-Version Datum Änderung Erstmalige Definition Erweiterung Benutzerspezifische Nachrichten 2 Definitionen Nachrichten bezeichnen hier Informationspakete die Benutzern auch als Nachricht bzw. Updates im Clientprogramm präsentiert werden. Zugriffe sind im Folgenden einzelne Anforderungen an die Schnittstellen durch Ihre Webseite. Sie bestehen aus Anfrage und Antwort. 3 Ziel Die PageFormant API macht die Funktionalitäten der PageFormant Dienste für Entwickler verfügbar. Dabei steht besonders auf Einfachheit der Benutzung als auch die Sicherheit der Daten im Fordergrund. Folgende APIs werden zur Integration in eigene Webseiten zur Verfügung gestellt: Versenden von, womöglich benutzerspezifischen, Nachrichten Es existiert zur Zeit eine Schnittstelle zur PageFormant API: Name-Value Pair (NVP) Schnittstelle Anfragen und Antworten werden über einfaches HTTP(S) gesandt. Diese Schnittstelle ist simpel gehalten, leichtgewichtig und einfach zu benutzen. Sie wird für skriptbasierten Einsatz empfohlen. 4 API Client-Server Architektur Alle in diesem Dokument beschriebenen Schnittstellen folgen der selben Client-Server basierenden Architektur. Ihre Webseite ist dabei Client der PageFormant Server. Damit ihr Server die PageFormant API Nutzen kann, müssen Sie, nach Freischaltung Ihrer Webseite im PageFormant System, API-Rechte beantragen. Diese werden aktuell automatisch vergeben. Danach finden Sie, auf der Informationsseite der jeweiligen Seite, die Informationen zu API-Key und API-Passwort. Diese beiden Angaben benötigen Sie zur Authentifizierung und Authorisierung ihrer Zugriffe und müssen bei jedem Zugriff mitgesendet werden. Wichtig: Der Zugriff auf die API ist auf aktivierte und freigeschaltete Webseiten mit ebenfalls aktiven und freigeschalteten Besitzer beschränkt. Eine Seite oder Hintergrunddienst Ihrer Webseite initialisiert, durch Senden einer Anfrage an unsere Schnittstelle, eine Aktion auf einem PageFormant API Server. Der PageFormant Server antwortet darauf mit einer Bestätigung des Erhalts Ihrer Anfrage durch Senden einer Erfolgsnachricht oder des/der aufgetretenen Fehler. Die Antwort enthält womöglich zusätzliche Informationen bezüglich Ihrer Anfrage.

2 5 Name-Value Pair Schnittstelle Die Name-Value Pair (NVP) Schnittstelle ermöglicht parameterbasierte Zugriffe auf die PageFormant API. Sie realisieren einen Zugriff durch Senden einer gemäß den nachfolgenden Prinzipien und Definitionen bestimmten HTTP-Anfrage an unsere Schnittstelle und erhalten eine den gleichen Prinzipien folgenden HTTP-Antwort. Ein Aufruf der NVP-Schnittstelle besteht aus einer URL-kodierten Zeichenkette von verknüpften Namen-Wert-Paaren (URL-Encoding nach RFC 3986), welche per HTTP-POST an die API-URL gesendet wird. Beispiel einer solchen Zeichenketten: APIKEY=IDENTIFIZIERENDERKEY&APIPASSWD=meingeheimespasswort&METHOD= PostMessage&SERVICEID=123&MESSAGE=... Die Antwort unserer Server ist ebenfalls URL-encodiert: ACK=SUCCESS ACK=ERROR&ERRORCODE=100&ERRSTR=Internal%20Server%20Error. Die URL für NVP Zugriffe lautet: Der Zugriff aktuell sowohl über HTTP als auch über HTTPS möglich. Eine spätere Beschränkung auf HTTPS ist vorgesehen. 5.A Request-Format Eine NVP-Anfrage besteht aus erforderlichen und optionalen n. namen sind schreibungsabhängig und immer groß zu schreiben. Die folgende Tabelle bietet eine Aufstellung über die, unabhängig von der aufgerufenen Methode, erforderlichen. METHOD erforderlich Aufzurufende Methode. Verfügbare Methoden und ihre werden in Abschnitt 5.B erläutert. APIVERSION erforderlich Versionsnummer des NVP Dienstes. Die PageFormant Server prüfen diese Nummer auf Aktualität und werden, außer in besonderen Ausnahmefällen, Zugriffe auf veraltete Versionen ablehnen. APIKEY erforderlich Eindeutige Identifizierung der Zielseite der Operation. Sie finden diese Information auf der Informationsseite ihrer Webseite im Betreiberbereich auf Pageformant.de APIPASSWD erforderlich Geheimes Passwort Ihrer Webseite. Es dient der Authentifizierung ihres Zugriffs. Wichtig: Sie müssen ihr API-Passwort geheim halten. Zusätzliche sollten Sie auch den API Schlüssel nicht an fremde weitergeben. Prüfen Sie Möglichkeiten diese Werte an einem sicheren Ort außerhalb des document root Ihres Webservers zu lagern und die Dateirechte so zu setzen, dass nur der Systemnutzer, der Ihre Software ausführt, darauf zugriff hat.

3 5.B Funktionen 5.B.i PostMessage Nachricht absetzen Die Methode PostMessage bietet Ihnen die Möglichkeit, Nachrichten direkt von Ihnen Webseite bzw. Webservices an Ihre Abonnenten auf PageFormant weiterzuleiten. Dazu müssen Sie im Betreiberbereich einen Dienst für Ihre Webseite erstellt haben. Tabelle 1 gibt für diese Methode spezifische an. SERVICEID Erforderlich Identifizierung des Dienstes, dem diese Nachricht zugeordnet werden soll. MESSAGE Erforderlich Nachricht die Benutzern als Information angezeigt werden soll. Maximal 180 Zeichen. LINK Erforderlich URL, zu der Benutzer geleitet werden sollen, wenn sie Ihre Nachricht anklicken. Diese muss existieren. USERSPECID Erforderlich Identifiziert Benutzer, die diese Nachricht exklusiv erhalten sollen. Kann leer gelassen werden, wenn alle Abonnenten des übergebenen Dienstes benachrichtigt werden sollen. Siehe 6.A.iii Zugriff auf Pageformant-API. Tabelle 1: PostMessage- 5.C Response-Format Nachfolgend werden die von den PageFormant Servern zurückgegebenen erläutert. ACK Erforderlich Enthält im Fehlerfall ERROR, sonst SUCCESS. Dieser indiziert den Ausführungsstatus ihrer Anfrage. ERRORCODE Optional Dieser ist nur im Fehlerfall (ACK = ERROR ) gesetzt. Er gibt eine Zahl an, die den aufgetretenen Fehler eindeutig identifiziert. Sie können diese in der Tabelle 3 nachsehen. ERRSTR Optional Dieser ist nur im Fehlerfall (ACK = ERROR ) gesetzt. Er gibt eine kurze des aufgetretenen Fehlers an. Zum Beispiel: You are using an unsupported API version. Tabelle 2: Übersicht Response Format 5.D Fehlercodes Aufrufe an die PageFormant API können aus diversen Gründen fehlschlagen. Die nachfolgende

4 Tabelle gibt einen Überblick über alle Möglichen Fehle und eine kurze. Fehlercode 101 Sie haben über HTTP-GET versucht auf die API zuzugreifen. Der Zugriff ist nur über HTTP-POST gestattet. 102 Ihre Anfrage enthielt nicht alle nötigen. Diese können entweder allgemeine oder Funktionsspezifische sein. Näheres dazu in den jewieligen Abschnitten. 103 API Schlüssel oder API Passwort ist falsch. Es wurde keine Webseite mit diesen Werten gefunden. 104 Ihre Webseite, oder der Besitzer ist nicht aktiv bzw. freigeschaltet. 105 Zurzeit unbenutzt. 106 Die angefragte Funktion, übergeben durch den METHOD-, existiert nicht. 107 Die übergebene API Version wird nicht unterstützt bzw. ist veraltet. Sie sollten ihre Skripte anpassen um die neuste Version des API zu nutzen. 108 Die Versuchen auf die API über reines HTTP zuzugreifen. 200 Es existiert kein Dienst mit der von Ihnen übergebenen Identifizierung. 201 Der von Ihnen übergebene Link existiert nicht bzw. ist ungültig. 202 Der zugeordnete Benutzer konnte nicht gefunden werden. (Benutzerspezifische Nachricht) Tabelle 3: Fehlercodes 6 Weitere Funktionen 6.A Benutzerspezifische Nachrichten 6.A.i Einführung Benutzerpezifische Nachrichten ermöglichen Ihnen, Nutzer Ihrer Webseite über nur für sie relevante Ereignisse zu informieren. Die Nutzer von Ihnen für sie bereitgestellte benutzerspezifische Nachrichten über die Auswahl von gewünschten Diensten filtern. So können Sie ihre Benutzer zum Beispiel bei Empfang von privaten Nachrichten informieren. Diese Funktion ist optional. Sie kann jedoch nur verwendet werden, wenn Ihr Server vorher per OAuth mit PageFormant verbunden wird. Was dazu nötig ist wird folgend erklärt. 6.A.ii OAuth-Verbindung OAuth ist ein offenes Protokoll zur sicheren API-Autorisierung von Webapplikationen. Um die PageFormant-Anbindung zu benutzen muss Ihr Server die Service Provider -Funktion ( Dienstanbieter ) erfüllen. Bevor ein Nutzer diese Anbindung verwenden kann, müssen Sie die dazu nötigen Einstellungen im Betreiberbereich auf Pageformant.de treffen (mehr dazu im Abschnitt 6.A.iv Einstellungen). Folgend werden die für diesen Vorgang relevanten Teile des Oauth-Protokolls (1.0a) paraphrasiert. Die genaue Spezifikation finden Sie hier: Generell benutzen PageFormant-Server zur Signierung das HMAC-SHA1-Verfahren.

5 Wenn ein PageFormant Nutzer, der ebenfalls Ihr Nutzer ist, benutzerpezifische Nachrichten aktivieren möchte, verbindet sich unser Server mit Ihrem, um einen Token, der diesen Vorgang der Autorisierung identifiziert, anzufordern. Dabei wird als Callback URL gemäß OAuth- Spezifikation oob gesendet, um auf eine out-of-band -Konfiguration hinzuweisen. Danach wird der Nutzer auf Ihre Webseite weitergeleitet, um nach dem Login den Zugriff von PageFormant auf seine Daten zu autorisieren. Hinweis: Hier sollten Sie Ihren Benutzer auf die Informationen, die Sie an PageFormant schicken, hinweisen. Nun sollten Sie einen Bestätitgungscode generieren, mit dem autorisierten Token verbinden, und dem Nutzer anzeigen. Dieser dient der Bestätigung der Verbindung. Diesen Code gibt der Nutzer bei PageFormant ein. Nun meldet sich der PageFormant-Server erneut bei Ihnen, diesmal mit dem Bestätigungscode ( Verifier ). Sollte dieser mit dem zuvor erstellten übereinstimmen, sollten sie den Token autorisieren. Zuletzt meldet sich der PageFormant-Server nochmals bei Ihnen um den autorisierten Token in einen neuen Access -Token umzuwandeln. Dieser identifiziert von nun an eindeutig die Verbindung für diesen Nutzer. Er wird beim Zugriff von PageFormant auf Ihre Webseite benutzt. 6.A.iii Zugriff auf Pageformant-API Wenn Sie nun auf die PageFormant-API Zugreifen und dabei Benutzerspezifizierung ermöglicht wird (z.b. PostMessage), wird der generierte Access-Token zur Identifizierung genutzt. Senden Sie in diesem Fall den SHA1-Hash des Token-Key. 6.A.iv Einstellungen Im Betreiberbereich auf Pageformant.de können Sie unter Benutzerpezifizische Nachrichten aktiviert? benutzerpezifische Nachrichten für Ihre Seite(n) aktivieren. Dazu sind folgende Einstellungen zu treffen: OAuth-Schlüssel ihres Servers: Schlüssel des auf Ihrem Server angelegten Consumers, den PageFormant zum Zugriff nutzen soll. OAuth-Geheimnis ihres Servers: Analog dazu, das zugehörige Geheimnis. Request Token -URL: URL zur Anforderung eines Request Token. User Authorization -URL: URL zur Autorisierung eines Request Token mittels Bestätigungscode. Access Token -URL: URL zur Anforderung eines Access Token, mittels bestehenden, autorisierten, Request Token. Ping -URL: Diese URL wird regelmäßig von den PageFormant-Servern für alle aktivierten OAuth-Verbindungen mit ihrem Server aufgerufen, um die Existenz des Benutzers und der Aktivierung der OAuth-Verbndung zu testen. Ihr Server sollte mit einer nicht-leeren Antwort und HTTP Code 200 antworten.