(:pagelist trail=Entwickler/Superconnector-content fmt=trailmenu:)
Einführung
Der Superconnector ist ein RESTful Web Service und folgt damit Roy Fieldings REST Architektur. Die zur Verfügung gestellten Ressourcen werden als XML-Dokumente repräsentiert. Es werden also HTTP (RFC 2616) benutzend XML-Dokumente hin- und hergesendet, wobei die vier HTTP Verben GET, POST, PUT und DELETE verwendet werden. Jede Ressource hat ihre eigene URI und kann unabhängig von den anderen verändert werden.
Authentifikation
Die Benutzung des Superconnectors erfolgt über HTTPS (RFC 2818) und verwendet "HTTP Basic Authentication" (RFC 2617). Als Nutzername und Passwort werden dieselben verwendet, die auch für das normale Stud.IP-Login verwendet werden. Unter Verwendung von cURL sähe das so aus:
(:source lang=bash:)
curl -u johndoe:secretpassword https://mystudip.net/superconnector/users
(:sourceend:)
TODO (mlunzena): Vielleicht ändert sich das?
Lesen mit der API
Lesen kann man entweder einzelne oder Collections von Nutzern/Veranstaltungen/etc. Die Collections implementieren derzeit keine Pagination. Das wird sich natürlich ändern müssen.
Zugriff auf diese Aktionen hat man per GET-Request an die entsprechenden Ressourcen.
Zwei Beispiele, die curl benutzen:
(:source lang=bash:)
curl -u user:password https://mystudip.net/superconnector/users
(:sourceend:)
(:source lang=bash:)
curl -u user:password https://mystudip.net/superconnector/user/76ed43ef286fb55cf9e41beadb484a9f
(:sourceend:)
Wenn das Lesen erfolgreich war, bekommt man eine XML-Response (Content-type: application/xml) mit Status-Code "200 OK". Die Ausgaben der Beispiele wären zum Beispiel:
(:source lang=xml:)
<users>
<user>
<user_id>76ed43ef286fb55cf9e41beadb484a9f</user_id>
<username>root@studip</username>
<perms>root</perms>
<Vorname>Root</Vorname>
<Nachname>Studip</Nachname>
<Email>root@localhost</Email>
[…]
</user>
<user>
<user_id>205f3efb7997a0fc9755da2b535038da</user_id>
[…]
</user>
</users>
(:sourceend:)
und für das zweite Beispiel:
(:source lang=xml:)
<user>
<user_id>76ed43ef286fb55cf9e41beadb484a9f</user_id>
<username>root@studip</username>
<perms>root</perms>
<Vorname>Root</Vorname>
<Nachname>Studip</Nachname>
<Email>root@localhost</Email>
[…]
</user>
(:sourceend:)
Schreiben mit der API
Erstellen, editieren und löschen sind ebenso einfach, können jedoch nicht einfach im Browser vollzogen werden. Mit curl kann man es aber unproblematisch ausprobieren.
Wenn man Ressourcen erstellen oder editieren möchte, sendet man das XML der Ressource im "body" des Requests an den Superconnector.
Wieder zwei Beispiele, um eine neue Ressource anzulegen (POST-Request), einmal "inline" und einmal über eine Datei:
(:source lang=bash:)
curl -u user:password -X POST -d '<user><username>wumpe</username><Vorname>Max</Vorname><Nachname>Mustermann</Nachname><perms>autor</perms><Email>max@mustermann.name</Email>[…]</user>' https://mystudip.net/superconnector/users
(:sourceend:)
(:source lang=bash:)
curl -u user:password -X POST -d @user.xml https://mystudip.net/superconnector/users
(:sourceend:)
Das Ergebnis eines erfolgreichen Anlegens ist Status-Code "201 Created". Die URL der neuen Ressource findet sich im Location-Header. Ausserdem findet sich das komplette XML der angelegten Ressource in dieser Antwort. Damit erhält man direkt die Attribute, die erst beim Anlegen im Superconnector erzeugt werden (Bsp: mkdate, chdate).
Editieren von Resourcen wird über PUT-Requests ausgeführt:
(:source lang=bash:)
curl -u user:password -X PUT -d @user.xml https://mystudip.net/superconnector/user/76ed43ef286fb55cf9e41beadb484a9f
(:sourceend:)
Die erfolgreiche Antwort ergibt einen Status von "200 OK".
Löschen kann man schlussendlich mit einem DELETE-Request:
(:source lang=bash:)
curl -u user:password -X DELETE -d @user.xml https://mystudip.net/superconnector/user/76ed43ef286fb55cf9e41beadb484a9f
(:sourceend:)
Die erfolgreiche Antwort ergibt auch hier einen Status von "200 OK".
Fehlerbehandlung
Schlägt ein Request fehl, wird ein passender HTTP-Statuscode zurückgeliefert. Ein Beispiel wäre:
(:source:)
HTTP/1.1 404 Resource could not be found
(:sourceend:)
Konventionen in der Dokumentation
In der folgenden Dokumentation wird folgende Notation verwendet:
{text}: weist darauf hin, dass der Text durch entsprechende Angaben gefüllt wird.
[…]: bedeutet, dass Auslassungen vorgenommen wurden, um die Dokumentation kürzer darstellen zu können. Im Referenzteil wird jeweils eine volle Beschreibung der Repräsentation der Ressourcen angegeben.
