search

OParl / spec

Spezifikation für eine offene Schnittstelle für Ratsinformationssysteme
https://oparl.org
Creative Commons Attribution Share Alike 4.0 International
61 stars 21 forks source link

Dokumentation | Liste reservierter URL-Parameter überarbeiten #241

Closed sterni24 closed 10 years ago

sterni24 commented 10 years ago

Hier steht noch Link Data drin. Skip fehlt.

Bei den Parametern würde ich noch die möglichen Werte ausweisen.

akuckartz commented 10 years ago

Die Reservierung von Schlüsselworten auch für die eventuelle Verwendung in zukünftigen Versionen von Spezifikationen ist eine seit den 50er Jahren geübte Praxis: http://en.wikipedia.org/wiki/Reserved_word

Der Sinn der Liste der reservierten Parameter bestand (besteht?) nicht vorrangig darin gleichzeitig auch deren Bedeutung vollständig zu definieren.

sterni24 commented 10 years ago

Diesen Kommentar verstehe ich nicht. Wenn in den URL mit Parametern gearbeitet wird, erwarte ich von einer Dokumentation eine Übersicht der gültigen Werte bzw. Wertebereiche.

@akuckartz Der Link war nicht besonders hilfreich. Die möglichen Werte von "listformat" sind dort nicht beschrieben.

akuckartz commented 10 years ago

Eventuell ist es sinnvoll für die Parameter mit definierter Bedeutung Verweise auf die jeweils relevanten Abschnitte des Dokuments aufzunehmen.

marians commented 10 years ago

Danke für die Eröffnung des Issues! Es ist zu sehen, dass hier Handlungsbedarf besteht.

Ich bin auch der Meinung, dass Links zum entsprechenden Teil der Spec sinnvoll wären. startdate und enddate werden beispielsweise unter "Objektlisten" beschrieben.

Gerade ist mir auch aufgefallen, dass in der Liste noch "callback" genannt wird, obwohl wir JSONP nicht mehr unterstützen. Das nehme ich raus.

Die Reservierung von subject, predicate, object ist bislang ohne weitere Diskussion erfolgt, wenn ich das richtig sehe.

marians commented 10 years ago

Zum Parameter "skip_id": Der entstammt dem Beispiel zur Paginierung. Es handelt sich dabei nicht um einen von OParl vorgegebenen URL-Parameter. Wie generell, gilt auch dort, dass der Server eine URL vorgeben darf. OParl nimmt keinen Einfluss auf deren Gestaltung.

Das heißt: Sie können hier bestimmen, welche URLs Ihr System für den Aufruf der nächsten, vorigen, ersten oder letzten Listenseite ausgibt. So wie Sie letztlich selber entscheiden, wie Sie die stabile Sortierung der Liste implementieren.

Ich werde versuchen, das unter Paginierung durch einen zusätzlichen Hinweis zu klären, wie wir ihn auch an anderer Stelle schon haben.

marians commented 10 years ago

Zum "skip_id"-Parameter bzw. der Gestaltugn der Paginierungs-URLs. Hier ist mir gerade aufgefallen, dass wir bereits die folgende Formuliertung im Abschnitt "Paginierung" haben:

Server-Implementierer entscheiden selbst, wie die URLs zum Abruf einzelner Listenseiten aufgebaut sind und tragen damit selbst Verantwortung für die Funktionsweise der Paginierung.

Ich habe diesen Hinweis nun so erweitert:

Die im obigen Beispiel verwendete URL einschließlich des fiktiven URL-Parameters dienen lediglich der Veranschaulichung und sind in keiner Weise bindend.

akuckartz commented 10 years ago

Die Reservierung von subject, predicate, object ist bislang ohne weitere Diskussion erfolgt, wenn ich das richtig sehe.

Wenn es Widerspruch dagegen gibt, dann wäre dazu eventuell ein Issue sinnvoll.

sterni24 commented 10 years ago

Gehört das nicht zum Thema tripel und somit zu JSON-LD? Wenn nein, dann fehlen mir dazu weitere Erläuterungen in der Doku.

akuckartz commented 10 years ago

@sterni24 Es geht bei den drei Parametern um eine eventuell zukünftig zu verwendende Abfragespache. Es geht um die Reservierung für die Zukunft, nicht um die jetzige Verwendung. Der Sinn solcher Reservierungen ist insbesondere, dass Server-Hersteller diese nicht für andere Zwecke verwenden.

(Nebenbei: In OpenGovLD werden genau diese drei Parameter mit hoher Wahrscheinlichkeit verwendet werden. Es ist aber auch nicht ausgeschlossen, dass ein flexiblerer Mechanismus verwendet werden wird, der die Notwendigkeit fester Parameternamen reduziert.)

sterni24 commented 10 years ago

Ich würde trotzdem den Parameter "skip_ID" als Empfehlung für die Paginierung aufnehmen. Wenn nicht kann diese issue auch geschlossen werden.

marians commented 10 years ago

Der Parameter "skip" bzw. "skip_id" deutet an, dass die Sortierung anhand der ID erfolgt und nun bei Paginierung alles bis zu einer bestimmten ID übersprungen wird. Das ist eine Möglichkeit. Da wir aber den Server-Implementierern nicht vorschreiben wollen, wie sie die Sortierung im Detail lösen, ist es aus meiner Sicht nicht sinnvoll, diesen Parameter zu empfehlen.