Ginkgo-API: Erste Designentscheidungen

15 Dez

Die letzten Tage habe ich mich damit beschäftigt, wie Anforderungen in den Bereichen Sicherheit, Versionierung, Dokumentation, Ressourcen-/Repräsentationenaufbau in Rails umsetzbar sind.

Sicherheit

Ginkgo muss auf jeden Fall zum OAuth2.0-Provider werden, was gleich zwei Vorteile bietet. Einerseits ermöglicht dies eine standardisierte Nutzer-Authentifizierung, andererseits ist es so möglich, die Schnittstellenutzung zu kontrollieren. Indem ginkgo einen Consumer-Key an Apps vergibt, die diesen Key bei jeder Anfrage direkt oder indirekt mitschicken, können bösartige Apps erkannt und einfach ausgesperrt werden. Würde die ginkgo-API nur HTTP-Authentifizierung unterstützt, könnte nur der Nutzer erkannt werden aber nicht die Applikation.

Es wäre schön gewesen, wenn dieser Provider gleich als Erweiterung des aktuell in ginkgo benutzen Authentifizierungs-GEMS mit devise_oauth2_providable erstellt werden könnte. Leider klappt dies aber wegen der unterliegenden Mongo-Datenbank nicht.

Mit dem oauth-plugin hatte ich schon mehr Erfolg. Hiermit konnte ich nach leichten Anpassungen eine Seite erstellen, auf denen sich neue Apps registrieren und einen Consumer-Key holen können.

Rückgabeformat / Versionierung

Zu diesen Themen gibt es verbitterte Diskussionen im Netz.
Am besten wird es wohl sein, wenn ginkgo ein eigenen, von application/json abgeleitete Medientyp definiert: z.B. application/vnd.ginkgo-v1+json.

Falls es nicht rückwärts-kompatible Änderungen in der API geben wird, können neue Clients dann in der HTTP-Anfrage mit Accept: application/vnd.ginkgo-v2+json die neue Version anfordern. Das wäre auch implementierungstechnisch eine sauberer Trennung.

Ich kann im Moment noch nicht einschätzen, ob solch ein eigener Medientyp für iOS/Android-Apps oder aus JavaScript heraus zu Problemen führt. Im Endeffekt kommt aber ein valider JSON-String zurück.

Dokumentation

Da eine manuelle Dokumentation und die wirkliche Implementierung schnell auseinander laufen, wäre es durchaus nicht schlecht, Felder und Links von Repräsentationen gleich IN der Repräsentation selbst zu beschreiben. Diesen Weg gehen Facebook und Twitter mit ihren API-Explorern. Ein spezieller Parameter wie z.B. http://api.ginkgosem.com/events/a432?metadata=1 könnte dann zusätzlich zu den sonstigen Daten Dokumentation mitliefern. Solch eine Art von Selbstbeschreibungsfähigkeit wäre natürlich sehr RESTful.

2 Antworten to “Ginkgo-API: Erste Designentscheidungen”

  1. wollepb 19. Dezember 2011 um 23:33 #

    Wie würden die Metadaten denn dann beschrieben und wo käme die Beschreibung her?

    • chrisupb 20. Dezember 2011 um 08:12 #

      Die Dokumentation der einzelnen Felder würde dann im Code (in den Views) stehen, der die Repräsentationen generiert. Die Dokumentation würde dann mitgelifert, wenn dies der Nutzer fordert.
      Für das E-Mail-Feld würde z.B. soetwas mitgeliefert:

      {
      … NUTZDATEN …
      „metadata“:[
      {
      „name“: „email“,
      „description“: „The contact email address granted by the user. , `string` containing a valid RFC822 email address.“
      }
      ]
      }

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: