Ausführungen zu HTTP Content Negotiation

[akuckartz]

Wird in Abschnitt 6025 ausgeführt.

[marians]

Im Moment ist der Abschnitt zu Content Negotiation eher als Exkurs in 4.1.7 Linked Data enthalten. Der Text danach, der momentan fälschlicherweise unter 4.1.8 Ziel steht, wird dadurch vom allgemeinen Linked-Data-Text abgeschnitten.

Wenn wir Content Negotiation beschreiben wollen, dann bitte in einem eigenen Abschnitt. Mir ist nur noch nicht klar, ob und warum wir das tun sollten. Kannst Du mich da mal überzeugen, @akuckartz?

[marians]

Zur Ergänzung: Ich sehe gerade, dass aktuell unter 4.3 ja ein Abschnitt zu Content Negotiation besteht. Dann würde IMHO bei 4.1.7 eine Fußnote genügen, um auf 4.3 zu verweisen.

[akuckartz]

Zu überzeugen versuche ich gerne, ich dachte aber, dass die erweiterten/geänderten Ausführungen zu John Doe dem Musiker das bereits tun.

Wo das genau steht ist mir eher egal. Ein Verweis per Fussnote o.ä. ist ok.

[marians]

Ich übernehme gerne das Aufräumen im Dokument.

Was ich aber noch nicht verstehe, ist was wir hier genau beschreiben. Ist Content Negotiation eine EMPFEHLUNG/MUSS/KANN? Wollen wir erreichen, dass von einem OParl-Objekt auf eine Web-Ansicht umgeleitet werden kann, wenn der Client nicht OParl möchte? Oder geht es um die Wahl zwischen kompakter und expandierter Form etc.? Das ist mir noch nicht klar.

[akuckartz]

Ziele:

• Sensibilisierung für dieses technische Detail
• EMPFEHLUNG zur Umleitung auf eine Web-Ansicht für Web-Browser

Mittels Content Negotiation können auch weitere Formate zwischen Client und Server ausgehandelt werden. Dazu muss in der OParl-Spezifikation aber nichts weiter gesagt werden.

Eine Wahl zwischen kompakt und expandierter JSON-LD Form erfolgt auf andere Weise (wenn es denn implementiert wird). Dazu gibt es an anderer Stelle einen informellen Hinweis auf die entsprechenden Spezifikationen (insbesondere JSON-LD).

[marians]

Danke für die Erläuterung!

Aus Entwickler-Sicht sehe ich auch einen Nachteil bei Content Negotiation: Ich gebe eine OParl-Objekt-URL in den Browser ein, um mir die JSON-Ausgabe anzusehen. Statt der erwarteten JSON-Ausgabe werde ich auf eine andere URL umgeleitet, auf der ich eine Webansicht des entsprechenden Objekts angezeigt bekomme.

Auf das Problem bin ich kürzlich übrigens bei dbpedia gestoßen, wo ich von der /resource/... auf die /page/... URL umgeleitet wurde. Dummerweise erfahre ich nicht, warum ich umgeleitet wurde.

Um das Problem zu umgehen, muss ich zunächst wissen, warum ich umgeleitet werde. Dann muss ich wissen, welche Header ich bei einer Anfrage setzen muss, um tatsächlich die gewünschte Ausgabe zu bekommen. Um das zu erfahren, muss ich wissen, wo ich dies erfahren kann. Diese Header muss ich dann setzen.

An der Stelle entfernen wir uns weit vom Ziel der Selbstbeschreibungsfähigkeit der API und erzeugen stattdessen Effekte, die man nur verstehen kann, wenn man die Dokumentation gelesen hat.

Daher bin ich dagegen, Content Negotiation überhaupt zu empfehlen und würde das Thema komplett auslassen.

[akuckartz]

@marians Es geht hier um die Architektur des Web. dbpedia.org geht korrekt damit um. OParl sollte dies auch tun.

Nicht jeder weiss, wie Content Negotiation funktioniert und wozu es da ist (so wie viele Entwickler auch andere Aspekte von HTTP nicht kennen). Grade deshalb ist es wichtig darauf in der Spezifikation einzugehen. Wenn jeder Entwickler den Inhalt der HTTP 1.1 Spezifikation kennen würde, dann wäre das nicht erforderlich. Ein Client muss wissen, welche Header er dem Server senden muss, um bestimmte Formate anzufordern. Ein Client, der von einem Server HTML anfordert (wie Webbrowser das üblicherweise tun) DARF nicht JSON oder JSON-LD vom Server geliefert bekommen.

Denn nur der Client kann wissen, mit welchen Formaten er etwas anfangen kann. Und Client und Server MÜSSEN sich an HTTP 1.1 halten - das steht aus gutem Grund auch in der OParl Spezifikation.

Als Entwickler möchte ich HTML bekommen, wenn ich es von einem Server anfordere und JSON-LD wenn ich angebe, dass ich das eher erhalten möchte. Wenn der Server mir nur JSON-LD anbieten möchte, dann mag er das tun, ich würde mich in dem Falle aber möglicherweise nach einem Sorftware- oder Service-Anbieter umsehen, der auch HTML automatisch liefern kann (und eventuell auch weitere Formate).

Man erwartet heutzutage ja auch, dass man in einem mobilen Webbrowser auf einem Smartphone eine lesbare HTML-Seite zu sehen bekommt. Da muss man als Entwickler zum Testen in einem Desktop-Browser auch entsprechende Vorbereitungen treffen.

Vor mir aus können wir gerne auch Tipps für Entwickler angeben. curl z.B. mag nicht besonders komfortabel sein, ich finde es inzwischen aber relativ praktisch auch für Testzwecke.

[pudo]

Ich habe zwar mit der OParl-Spec bisher wenig gearbeitet, aber @marians hat mich eingeladen zu kommentieren. Als Entwickler arbeite ich recht viel mit APIs und habe auch schon einige selbst gebaut - dabei finde ich, dass Pragmatismus wichtiger ist als HTTP-Theorie.

Bei API-Endpunkten JSON zurück zu geben ist erstens praktisch und zweitens m.W. nicht illegal - es bedeutet nur, dass der Server keine besseres Match hat. Das finde ich auch nicht unrealistisch - Webseiten, die im UI versuchen eins-zu-eins auf API-Ressourcen und -Collections zu mappen sind normalerweise Usability-Desaster.

Aber im Grunde frage ich mich: muss das wirklich in die Spec? Wenn die Spec sagt "da muss ein Accept:-Header sein", dann reicht das doch - warum müsst ihr den anderen case definieren, zumal wenn der eben gar nicht wirklich zu einer maschinenlesbaren API beiträgt?

[akuckartz]

@pudo Wenn ein Einstieg in eine Diskussion über die Entwicklung einer auch auf HTTP basierenden Spezifikation mit dem Ausspruch "Pragmatismus ist wichtiger als HTTP-Theorie" beginnt, dann klingeln bei mir im Kopf Alarmglocken. Jedenfalls überzeugt mich das (vorsichtig formuliert) nicht.

Ob "Webseiten, die im UI versuchen eins-zu-eins auf API-Ressourcen und -Collections zu mappen" "normalerweise" Usability-Desaster sind, ist ziemlich irrelevant solange das bei OParl nicht zu erwarten ist. Weshalb soll es z.B. zu einer oparl:Person oder einer oparl:Organizationkeine gut verwendbare html-Repräsentation geben können? Wenn es dazu konkrete Hinweise gibt, dann wären diese mögiicherweise hilfreich.

Dass ich den Begriff API in Zusammenhang mit OParl unpassend finde hatte ich an anderer Stelle schon angemerkt.

Was zu dem Thema konkret in die OParl-Spezifikation soll muss diskutiert werden. Die Hoffnung, dass ohne bestimmte Hinweise möglicherweise Unkenntnis über bestimmte Teile der HTTP 1.1 Spezifikation und der "HTTP-Theorie" bei Implementierern weiter bestehen bleibt hielte ich für keinen guten Grund diese nicht aufzunehmen.

[pudo]

Ok, lass uns das ein wenig sachlicher machen. Was ich mit "Pragmatismus vs. HTTP-Theorie" meinte, war lediglich: wir müssen irgendwie einen verständlichen Zugang zu Ratsinformationen schaffen, möglichst ohne dabei irgendwo in der Nähe von httpRange14 zu landen ;)

Ich sehe schlicht die Notwendigkeit, dass eine Spezifikation wie OParl 1) vorgibt, welche HTML-Repräsentationen es zu geben hat und 2) vorgibt, dass die API notwendigerweise deren URL kennt.

Beispiel: ich scrape jede Nacht das Dokumenteninformationssystem des Bundestags. Ich kann mir gut vorstellen, einen Teil dieser Daten als OParl-Schnittstelle anzubieten. Gleichzeitig will ich die Oberfläche meiner Seite vereinfachen und anstatt der ganzen Einzelseiten nur noch eine Abo-Maske anbieten, bei der User Updates aus einzelnen Themenbereichen als E-Mail bestellen können.

[akuckartz]

Zu http-range 14: https://plus.google.com/109693896432057207496/posts/Q7pCA6yqNtS :-)

[jehrhardt]

Aktuell stelle ich mir die Frage um was genau es in der Diskussion denn geht? Geht es darum, ob es einen Bereich gibt in dem Content Negotiation erklärt wird? Geht es darum, Content Negotiation in bestimmten Fällen als Teil der Spezifikation vorzuschreiben?

Grundsätzlich halte ich Content Negotiation für sehr sinnvoll und guten Stil bei der Umsetzung von HTTP Servern im allgemeinen und RESTful APIs im besonderen. Allerdings lässt sich Content Negotiation auf ganz unterschiedliche Weise HTTP 1.1 konform umsetzen, wobei es auch kein richtig oder falsch gibt.

Die Idee hinter Content Negotiation ist, dass ein Client die von ihm akzeptierten Repräsentationen im Accept Header des Requests mitgibt, damit der Server gemäß Spezifikation die am besten passende und von ihm unterstützte Repräsentation an den Client ausliefert. Der Haken ist allerdings, dass */* auch ein valider Accept Header ist und soviel bedeutet wie "ich nehme alles".

Was würde ich empfehlen?

Ein Server kann Content Negotiation über einen Redirect auf eine andere URL umsetzen, oder einfach die entsprechende Repräsentation ohne Redirect ausgeben. Beides ist valide und ich würde in der OParl Spezifikation weder Einschränkungen noch Empfehlungen vornehmen.

Ich würde kurz darauf hinweisen, dass Content Negotiation eine gute Sache ist und HTTP 1.1 konform umgesetzt werden sollte, wo immer das sinnvoll möglich ist.

Es gibt keine Regel, was passiert, wenn */* im Accept Header steht. Eine Webanwendung würde dann üblicherweise HTML ausgeben, da es die standard Repräsentation einer Webanwendung ist. Im Falle einer API, die standardmäßig mit JSON arbeitet, würde ich eben application/json als Antwort erwarten. Das vermeidet im Zweifel unnötige Verärgerung bei der tatsächlichen Zielgruppe. Ich würde daher in der OParl Spezifikation ausdrücklich darauf hinweisen, dass application/json die standard Repräsentation ist und in diesem Fall ausgegeben werden muss.

[akuckartz]

@jehrhardt Gerade weil das etwas kontrovers ist, halte ich es für sinnvoll auf das Thema einzugehen und zumindest die unterschiedlichen Meinungen und Möglichkeiten zusammenzufassen. So etwas wird auch in W3C Recommendations gemacht.

Ich halte es aber für möglich, dass wir letztendlich Konsens erreichen. Die Lösung kann durchaus in der Empfehlung mehrerer Alternativen bestehen oder im Ausschluss der einen oder anderen "Lösung", die man in freier Wildbahn finden kann.

Dass ein OParl-Client der explizit alles akzeptiert vom OParl-Server JSON-LD erhalten MUSS dürfte nicht umstritten sein. Jedenfalls halte ich das aktuell für empfehlenswert.

[akuckartz]

Ich habe nun aufgrund des Feedbacks und nach weiterem Nachdenken den Abschnitt überarbeitet. In der Hoffnung, dass das so konsens-fähig ist schliesse ich dieses Issue.

[marians]

Ich formulier das noch mal ein bisschen auf Leserlichkeit um ;-)