MAPI

From KWICK! Developer Wiki

Jump to: navigation, search

Die MAPI (Mobile API) ist die Schnittstelle zur Entwicklung von Anwendungen für mobile Endgeräte mit Zugriff auf die KWICK! Social Platform.

Die Kommunikation mit der MAPI erfolgt über aufgerufene Pfade sowie bestimmte Übergabeparameter. Der Pfad spiegelt hierbei die gewünschte Funktionalität wider, und die per HTTP GET oder HTTP POST übergebenen Daten die Werte der Übergabeparameter. Als Antwort erhält die Client-Applikation ein JSON-kodiertes Objekt, welches die angeforderten Daten enthält.

Contents

Request

Aufbau

Die einzelnen Anfragen werden stets an die MAPI-Adresse http://mapi.kwick.de/1.0/ gesendet, und der Pfad zur gewünschten Funktion wird angehängt. Hierbei steht 1.0 für die aktuelle Version der MAPI.

Die korrekte Request-URL für den Login ist damit beispielsweise:

http://mapi.kwick.de/1.0/login
       |                 | 
       |                 Aufgerufene Funktion
       |
       KWICK! MAPI Basis-URL

Beachte hierbei bitte unbedingt, dass für die meisten Services eine Authentifizierung in der MAPI notwendig ist.

Ablauf

Der Ablauf der Bearbeitung und Beantwortung eines Request stellt sich wie folgt dar.

  1. Request wird vom Client an die MAPI gesendet.
  2. Wenn die aufgerufene Funktion sessiongeschützt ist, verifiziert die MAPI die Session und den __auth-Parameter.
  3. Die Funktion wird mit den übertragenen Parametern aufgerufen.
  4. Die erstellte Antwort wird JSON-Kodiert an den Client übertragen.

Fehlerbehandlung

Alte Methode

Tritt bei einer Anfrage ein Fehler auf, gibt die MAPI diesen zurück an den aufrufenden Client. Das JSON-Rückgabeobjekt hat in diesem Fall folgende Form:

Name Datentyp Beschreibung
errorMsg String Die Beschreibung des aufgetretenen Fehlers

Beispiel

{
	errorMsg: "Es ist ein Fehler aufgetreten"
}

Neue Methode

Aktuell nur in folgenden Services: Blog. Neuere Services übergeben ausführlichere Daten. Das JSON-Rückgabeobjekt hat dann im Fehlerfall die folgende Form:

Name Datentyp Beschreibung
error Boolean Zeigt an, ob ein Fehler aufgetreten ist
errorCode Integer Fehlercode (global oder service-spezifisch)
errorMsg String Die Beschreibung des aufgetretenen Fehlers

Beispiel

{
	error: true,
	errorCode: 500,
	errorMsg: "Ein interner Fehler ist aufgetreten"
}

Im Erfolgsfall geben diese Services auch den Schlüssel error mit. Dieser ist dann natürlich false. Somit kann über diesen Wert geprüft werden, ob ein Fehler aufgetreten ist ohne mehr oder weniger umständlich die Existenz bestimmter Schlüssel zu prüfen.

Beispiel

{
	error: false,
	// Alle anderen Werte der Rückgabe
}

Globale Fehlercodes

Aktuell nur in folgenden Services: Blog. Die folgenden Fehlercodes gelten global und können von allen Services zurückgegeben werden. Die globalen Fehlercodes orientieren sich an den HTTP Status Codes.

Name Beschreibung
401 Der Benutzer ist nicht eingeloggt. Diese Aktion ist aber nur für eingeloggte Benutzer verfügbar.
403 Der Benutzer darf diese Aktion nicht durchführen.
404 Das angeforderte Objekt wurde nicht gefunden.
500 Ein interner Fehler ist aufgetreten.
503 Diese Aktion kann im Moment nicht durchgeführt werden. Eine Wiederholung ist in Kürze vermutlich erfolgreich.

Services

Die unterschiedlichen Funktionalitäten sind abstrahiert in einzelne Services zusammengefasst.

Unterschieden wird zwischen den folgenden Services:

Des Weiteren besteht eine Funktion zur Abfrage der MAPI-Version.

Personal tools