Vor ungefähr zwei Monaten hat Microsoft eine REST API für den Visual Studio Online, den auf Team Foundation Server basierten Cloud-Dienst, veröffentlicht. Die Visual Studio Online REST API ermöglicht dem Benutzer, diverse Abfragen gegen Visual Studio Online durchzuführen. Mit der REST API können nun auch neue Integrationsszenarien umgesetzt werden. Eine Referenz zur Visual Studio Online REST API wurde ebenfalls veröffentlicht.
Microsoft stellt für die Entwickler einige Tutorials bereit. Wie sich jedoch herausstellte, ist in einem Tutorial an entscheidender Stelle ein Fehler. Hier erfahren Sie, wie es richtig geht.
Um Daten aus einem Visual Studio Online Konto abfragen zu können, muss der Benutzer authentifiziert werden. Bei Visual Studio Online gibt es dazu zwei mögliche Ansätze. Zum einem kann die Basic Authentification in Anspruch genommen werden. Mit diesem Ansatz werden zusammen mit der Abfrage die Credentials (Benutzername und Passwort) verschickt. Dies eignet sich besonders dazu, wenn man eine Desktop-Anwendung entwickelt oder man einfach die neue REST API testen möchte.
Zum anderen stellt die Visual Studio Online REST API die OAuth Authentifizierung zur Verfügung. Diese Option ist vor allem für solche Szenarien geeignet, in denen man den Benutzer nicht ständig dazu auffordern möchte, sich einzuloggen. Das wäre zum Beispiel im Fall eines Cloud-Dienstes, der ein Integrationsszenario mit dem Visual Studio Online realisiert. Mit der OAuth Authentifizierung gewährt der Nutzer dem Cloud-Dienst das Recht, in seinem Namen Abfragen gegen den Visual Studio Online durchzuführen. Mehr dazu unter OAuth 2.0 Authorization Framework.
Auf dem Visual Studio Online Portal befindet sich ein Tutorial, das dem Entwickler Schritt für Schritt die Anwendung der OAuth mit dem Visual Studio Online erklärt. Der Prozess besteht aus vier Schritten. Zuerst muss der Entwickler seinen Cloud-Dienst im Visual Studio Portal registrieren. Dann muss er den Benutzer in seiner Anwendung auf den speziellen, von Visual Studio Online bereitgestellten URL umleiten. Dort autorisiert der Benutzer den Cloud-Dienst für seinen Microsoft Account. Seit diesem Zeitpunkt kann der Cloud-Dienst im Namen des Benutzers auftreten. Im dritten Schritt erhält der Cloud-Dienst vom Visual Studio Online Informationen, die mit dem Benutzer verknüpft sind. Die Informationen sind dazu notwendig, um einen Token für den autorisierten Benutzer beim Visual Studio Online anzufordern. Der Token wird dann in die Headers eines http-Request mit einer REST-Abfrage hinzugefügt, um die Authentifizierung des Benutzers zu ermöglichen.
Wer jedoch der Anleitung auf der Seite folgt, stößt schließlich auf ein Problem: obwohl man den Token als Header dem REST-Request hinzugefügt hat, wie im Tutorial beschrieben, bekommt man als Response keinen JSON-String mit erwarteten Informationen, sondern einen String mit HTML-Code. Nach der Analyse des HTML Codes kann man feststellen, dass die Response eine WWW-Seite beinhaltet, die den Benutzer auffordert, sich einzuloggen – was eigentlich durch den Einsatz von OAuth hätte vermieden werden sollen.
Um die Ursache des fehlerhaften Verhaltens herauszubekommen, war es sehr hilfreich, sich den ausgehenden http-Request anzuschauen. Statt den erwünschten Header
Authorization: Bearer {access_token}
beinhaltete der Request einen solchen Header:
Authorization: Authorization: bearer {access_token}
Ein kurzer Blick in den Tutorial genügte, um den Übeltäter zu finden – der Fehler steckte in der Zeile:
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Authorization", "bearer " + {access_token});
Im Konstruktor der Klasse AuthenticationHeaderValue übergibt man zwei Strings. Mit dem ersten Argument wird der Token-Typ angegeben und soll er daher „Bearer“ heißen. (Access Token Types). Der zweite String ist der eigentliche Access Token.
Eine kleine Abänderung der Zeile hat den Zweck erfüllt:
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", {access_token});
Auf diese Art und Weise bekommt man bei einer REST-Abfrage gegen Visual Studio Online, wie erwartet, einen JSON-String.
PS. Inzwischen hat Microsoft den Tutorial angepasst und den Fehler behoben. Somit bleibt dem Entwickler viel Ärger erspart und er kann unverzüglich damit anfangen, die neue REST API ausgiebig zu testen.