Ergebnisse der API-Analysen

20 Nov

Als letzte Aufgabe vor dem wirklichen Start der API-Konzeption für ginkgo habe ich mir die Analyse bestehender, öffentlicher APIs vorgenommen.
Das Ziel soll sein, die dortige Umsetzung typischer Anforderungen zu vergleichen und entsprechende Hinweise in die Konzeption der API für ginkgo einfließen zu lassen.

Um die Analysen zu strukturieren, betrachtete ich jeweils folgende Aspekte in drei Kategorien:

Eigenschaften

  • REST-Konformität: Die Stufe gemäß dem Modell von Richardson (siehe vorletzter Blogpost)
  • Versionierung: Wurde Schnittstellenversionierung umgesetzt und auf welche Art und  Weise ist dies geschehen?
  • Unterstützte Medientypen: Welche Antwortformate kann die Schnittstelle zurückliefern?
  • Dokumentation: Ist die Dokumentation generiert oder manuell erstellt? Welche Elemente enthält sie und wie sind sie angeordnet?
  • Bibliotheken: Gibt es offizielle Bibliotheken für den Zugriff auf die Schnittstelle?

Sicherheit

  • API-Zugriff: Muss sich eine Anwendung besonders identifizieren, wenn sie die API nutzt?
  • Authentifizierung von Benutzern: Das oder die Verfahren, mit denen sich ein bestimmter registrierter Nutzer eines Dienstes authentifiziert.
  • Geschützte Ressourcen: Welche Ressourcen sind nicht öffentlich zugänglich?
  • Zugriffsbeschränkungen: Die maximale Anzahl von Anfragen oder sonstige Beschränkungen.

Besonderheiten

Was setzte die API auf besondere Art und Weise um?

Wenn ihr noch Tipps für Ergänzungen habt, gerne in den Kommentaren.

Schlussendlich habe ich Netflix, Facebook, Oracle Public Cloud und Mendeley analysiert.

Allgemeine Ergebnisse der Analyse:

Zur Absicherung von REST-APIs ist OAuth zum Standard geworden. Es ist zu beobachten, dass der Consumer-Key aus OAuth zusätzlich zu seinem eigentlichen Zweck, die Rolle eines klassischen API-Schlüssels (Überwachung der Dienstnutzung) einnimmt. Ganz anonyme Anfragen, selbst auf öffentliche Ressourcen, sind fast nie erlaubt.

Was die Rückgabeformate angeht, dominieren klar standardisierte Medientypen. Nur die Oracle Public Cloud definiert jeweils herstellerspezifische Typen. JSON löst XML zusehends ab.

Die für eine REST-Schnittstelle so wichtigen Beziehungen zu anderen Ressourcen werden durch die betrachteten Dienste auf sehr unterschiedliche Art und Weise realisiert. Während Netflix das link-Element aus HTML einsetzt und Facebook jegliche Links gar nicht weiter auszeichnet, setzt Oracle auf einen eigenen Medientyp der die Linksemantik sowie den Link an sich enthält.

Die Dokumentation für Schnittstellennutzer ist fast immer manuell erstellt. Nur Facebook bietet mit dem API-Explorer zusätzlich die Möglichkeit zur Erkundung der API in Echtzeit.

Überraschung: Facebook

Am meisten hat mich Facebook überrascht. Die neue Graph-API ist wirklich RESTful, obwohl sie auf den ersten Blick nicht so aussieht. Grundsätzlich startet man bei einer User-Ressource und gelangt über die sogenannten Connections zu allen referenzierten Ressourcen. Vorgegebene URL-Hierarchien wie z.B. /user/friends/likes gibt es nicht.
Äußerst produktiv für Schnittstellennutzer ist auch, dass mit der Antwort gleich eine Beschreibung aller Felder und Datentypen angezeigt werden kann (Das Stöbern in veralteten Dokumentationen entfällt damit). Genau solche selbst beschreibenden Repräsentationsformate fordert REST!
Im  Anhang habe ich einfach mal eine Repräsentation der User-Ressource inlusive Metadaten angehängt: Facebook_User_Ressource

Eine Antwort to “Ergebnisse der API-Analysen”

  1. wollepb 21. November 2011 um 11:08 #

    Die Twitter API Console erlaubt auch live die API zu testen. https://dev.twitter.com/console

Schreibe einen Kommentar

Trage deine Daten unten ein oder klicke ein Icon um dich einzuloggen:

WordPress.com-Logo

Du kommentierst mit Deinem WordPress.com-Konto. Abmelden / Ändern )

Twitter-Bild

Du kommentierst mit Deinem Twitter-Konto. Abmelden / Ändern )

Facebook-Foto

Du kommentierst mit Deinem Facebook-Konto. Abmelden / Ändern )

Google+ Foto

Du kommentierst mit Deinem Google+-Konto. Abmelden / Ändern )

Verbinde mit %s

%d Bloggern gefällt das: