Ginkgo-API: Ressourcenstruktur und Aufbau von Repräsentationen

30 Dez

Ich bin alle im Trac gelisteten Features und das Domainmodell nochmals durchgegangen und habe die Adressierung der unterschiedlichen Ressourcen aktualisiert. Je flacher die Ressourcen-Struktur ist, desto weniger Anfragen muss ein Client machen, um an die gewünschte Information zu gelangen.

http://<domain>/api dient dann als Einstiegspunkt für den Client, um an die URLs der gewünschten Daten zu gelangen:

GET http://<domain>/api
{
„users“ : „http://<domain>/api/users&#8220;,
„conversations“ : „http://<domain>/api/conversations&#8220;
„events“ : „http://<domain>/api/events&#8220;
„locations“ : „http://<domain>/api/locations&#8220;
„institutions“ : „http://<domain>/api/institutions&#8220;
„catgeories“ : „http://<domain>/api/categories&#8220;
„submissions“ : „http://<domain>/api/submissions&#8220;
„search“ : „http://<domain>/api/serach&#8220;
„worldcloud“ : „http://<domain>/api/worldcloud&#8220;
„near-me“ : „http://<domain>/api/near-me&#8220;
}

Bis auf search, worldcloud und near-me sind alles Listenressourcen. Ein GET http://<domain>/api/events holt die Liste aller Events (paginiert, um zu verhindern, dass die halbe Datenbank geholt wird).

GET http://<domain>/api/events
{
„events“ : {
„href“ : „http://<domain>/api/events&#8220;,
„rel“ : „events“,
„total“ : „2“,
„elements“: [
{„name“ : „arnets11“, „href“ : „http://<domain>/api/events/rzh4028&#8220;},
{„name“ : „ost2012“, „href“ : „http://<domain>/api/events/gv5333g&#8220;}
]
}}

Um schneller an die gewünschten Informationen zu gelangen, gibt es für alle Listenressourcen die Konvention, dass durch Anhängen der ID eines Listenelements, dieses direkt abrufbar ist (an die ID gelangt der Client z.B. über die search-Ressource). Konkret: Der Client holt sich die URL der Listenressource für Events und fügt die ihm bekannte ID des Events an GET http://<domain>/api/events/rVFEDF4028.
Ebenso wird es möglich sein, Queryparameter an die URL einer Liste anzuhängen, um die Liste einzuschränken: http://<domain>/api/conversations?unread=true . Entweder sind generell alle Felder einer Ressource durchsuchbar oder nur spezielle Queryparameter werden in der Dokumentation definiert. Ich denke, Letzteres ist besser.

Neue Events werden durch ein POST auf die Events-Listenressource angelegt:

POST http://<domain>/api/events
{
„acronym“: „lald12“,
„name“ : „1st International Workshop on Learning Analytics with the Web of (Linked) Data“,
„type“ : „Conference“,
„start_date“ : „2012-03-13“,
„end_date“ : „2012-03-20“
}

Für Aktualisierungen von Ressourcen hatte ich ursprünglich auch POST vorgesehen (vgl. mein Blogpost). Dann funktioniert das automatische Routing von Rails aber nicht mehr, das ja PUT nutzt, um an die update-Methode im Controller zu routen. (Anmerkungen hierzu sind gerne erwünscht)

Was die Generierung (serialisieren und deserialisieren) von JSON in Rails angeht, bin ich immer noch kräftig am Rumprobieren. Ich habe schon mehrere GEMs durchprobiert aber irgendwie kann jedes GEM wieder etwas, was ein anderes nicht kann. Dazu werde ich aber noch einen eigenen Blogeintrag verfassen.

Eine Antwort to “Ginkgo-API: Ressourcenstruktur und Aufbau von Repräsentationen”

  1. wollepb 30. Dezember 2011 um 23:22 #

    Da ist ein Typo bei „wordcloud“

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: