Swagger

Swagger ist ein API-Broweser mit Playground. Müsste man mal evaluieren, wie gut man das für die API implemnetieren könnte.

• Grundstruktur generieren
• Objekttypen
• Post-Handling

changed the description

added 1 deleted label

mentioned in commit 4f951a63

changed the description

marked the checklist item Grundstruktur generieren as completed

Ab jetzt unter https://netvs-devel-devel.scc.kit.edu/swagger erreichbar.

mentioned in commit d972d853

marked the checklist item Post-Handling as completed

marked the checklist item Objekttypen as completed

mentioned in commit 8724ce06

changed title from Swagger? to Swagger

closed

removed 1 deleted label

mentioned in commit 1e630e29

beim anschauen ist mir aufgefallen, dass bei allen list-funktionen nur GET als methode dransteht. POST ist die hauptmethode fuer alle requests (und fuer list z.b. bei joins wichtig, aber auch in kombination mit dml-aufrufen).

Hä? Bei list-joins nutzt man doch das Transaction-Commit. Und POST für list ist IMHO komplett falsch.

wenn POST für list komplett falsch ist, wie willst du mit GET list-joins machen?

ah, ich weiss jetzt. ich hatte die varianten 'list' via /wapi/transaction/execute und /sys/ot/list als gleichwertig betrachtet, da sie intern identisch sind. auf http-ebene ist es natuerlich was anderes. deswegen aber POST fuer list-rq. extra zu sperren, scheint mir aber zu weit gegriffen.

habe den text dazu in [1] noch etwas angepasst. die parallelitaet von POST und GET fuer list-fkt. habe ich wg. der nullbarkeit von parametern dringelassen. der fall duerfte zwar selten sein, aber nicht ausgeschlossen. siehst du da noch unstimmigkeiten?

[1] https://www-net-devel-doku.scc.kit.edu/webapi/3.0/main/#get-request

Ah, ich sehe das Problem – warum nicht bei Nichtbesetzung den Default nehmen und wenn es keinen Default gibt null als Wert?

ah, weil leere Strings nicht direkt im GET gehen...

Obwohl: Semantisch kann man schon diskutieren, dass ein gesetzter Wert eher einem leeren String entspricht als ein nicht gesetzter Wert. Aber ja, nicht ganz einfach. Alternativ vielleicht auch: Null setzbar machen und an passenden stellen null als default setzten (sollte ja mittlerweile gehen, oder?)

(Also mit "gesetzt und leer meine ich: "/api?a&b". Hier sind a und b "ohne Wert" gesetzt.)

es geht nicht um die nullbarkeit an sich, sondern eher darum, dass der query string bei GET kein json ist. json ist aber das basisformat. und dafuer eignet sich me. nur POST richtig. weggelassene parameter stellen auch kein problem dar. es geht nur um angegebene parameter, die explizit null sein sollen.

"/api?a&b" fuehrt zu

{"a": "", "b": ""}

man will aber

{"a": null, "b": null}

bei list duerfte es aber kaum erforderliche parameter geben, dh. weglassen sollte kein problem darstellen (ausnahmen bestaetigen die regel). wie gesagt, der fall ist selten, und wenn er doch vorkommt, muss man halt POST entweder via list oder transaction/execute nehmen. vllt. kannst du mir noch erklaeren, warum POST fuer list falsch ist bzw. wo das festgelegt ist.

Zum letzten Punkt: https://tools.ietf.org/html/rfc2616#section-9.3

The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.

https://tools.ietf.org/html/rfc2616#section-9.5

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.

Oder aktueller, aber im text quasi gleich: https://tools.ietf.org/html/rfc7231#section-4.3.1 bzw. https://tools.ietf.org/html/rfc7231#section-4.3.3

danke fuers raussuchen,

also ich wuerde die einleitung zu POST und den ersten punkt (Providing a block of data...) in https://tools.ietf.org/html/rfc7231#section-4.3.3 nicht so auslegen, dass list (einzeln oder via TA) nicht als ein 'data-handling process' in frage kommen darf, also explizit falsch sein soll.

das eine heisst halt '/sys/ot/list' und das andere heisst '/wapi/transaction/execute', aber beide koennen sich identisch verhalten, wenn man in letzterem sys.ot.list spezifiziert (according to the resource's own specific semantics). trotzdem meinst du, dass das eine falsch ist und das andere nicht?

Naja, ich würde schon sagen, dass man die list-Funktionen im swagger als get angeben sollte und für joins das wapi/transaction/execute, unabhängig davon, ob darin nur listet oder nicht - ist dann eben abstrakter, da letzteres ja eh quasi alle API-Endpunkte nochmal abbildet.

ich fand den zusatz für POST nützlich, um das den benutzern offenzulegen, damit man eine übereinstimmung mit der text-doku sieht. sonst liest man in der doku "POST für alle fkt., GET zusätzlich auch für nicht-datenmod. fkt." und sieht aber im swagger, dass bei list nur GET ausgewiesen ist.

aber du kannst es von mir aus natürlich auch gern so lassen, wie es ist. ebenso die sortierung der models.

Ah, mir fällt gerade auf, dass ich im swagger mehr als eine Method angeben kann; das könnte man natürlich einbauen, dass bei nicht datamod-funktionen beide angezeigt werden :) Ich probier das mal demnächst aus.

vllt. die 'models' noch sortieren?

Ist ein dict und damit von natur aus unordered. Mal sehen, ob man das dem swagger einprüglen kann. Aber ich denke, der Teil unten ist nicht so wichtig und dient eher nur als Model für die Funktionen oben (oben werden sie z.B. für Returns referenziert).