Benennungen der API manchmal nicht ganz konsistent

bwl21

Sorry, dass ich da ein bisschen rumnörgle

Die Benennung des Rest-Api ist m.E. nicht immer ganz konsistent.

Aus dem Bauch heraus würde ich das so vorschlagen (Persons als Plural wie sonst auch).

/persons/masterdata
/persons/masterdata/grouptyperoles
/persons/masterdata/grouptyperoles/{roleId}

in dem Zuge stolpere ich immer wieder über

Der sieht immer so aus. als ob man da die Eigenschaften einer Person posten könne ...

Ich weiß, das ist schwierig das noch gerade zu biegen, aber offensichtlich habt ihr /masterdata/person ja auch schon zurückgezogen.

Vermutlich wird man hier ein Lifecycle management brauchen, und umbenannte API für eine Übergangsfrist parallel unterstützen müssen. Aber solche Inkonsistenten sollte man schon ausschwitzen.

davidschilling

Es gibt tatsächlich ein Schema wann etwas plural und wann etwas singular ist.

/persons liefert alle Personen
/persons/1 von allen Personen liefere nur die erste zurück
/person/masterdata hier bekommen wir die stammdaten aus einem modul und zwar dem Personen modul. Mehrzahl wäre hier komisch, da sich unterhalb von personen keine stammdaten verbergen
/persons/properties das ist nicht ganz optimal, aber immer noch besser als /person/properties und es folgt dem Schema, dass wir die properties von allen Personen bekommen

bwl21

@davidschilling Danke für deine Antwort. Bitte versteht das nicht falsch als pingelige Kritik. Ich denke aber viel über Namenskonventionen nach (in vielen jahren habe ich gelernt Namenskonvention ist Archtekturarbeit und nicht überflüssiges Beiwerk), daher fallen mir manche Dinge auf. In meiner Erfahrung sind Abweichungen von Konventionen zeitraubend, fehleranfällig und damit letztlich doch teuer. Dies um so mehr je komplexer ein System ist.

/person/masterdata hier bekommen wir die stammdaten aus einem modul und zwar dem Personen modul. Mehrzahl wäre hier komisch, da sich unterhalb von personen keine stammdaten verbergen

Genau, deshalb müsste es persons/masterdaten heissen, denn es sind die Masterdaten des persons (Personen) - Moduls. Es sind nicht die Masterdaten einer einzelnen Person. Dann wäre es konsistent zu persons/properties, welches Eigenschaften des persons liefert.

/persons/1 von allen Personen liefere nur die erste zurück

/persons/1liefert die person mit der ID 1, nicht unbedingt die erste - richtig?

davidschilling

@bwl21 sagte in Benennungen der API manchmal nicht ganz konsistent:

Genau, deshalb müsste es persons/masterdaten heissen, denn es sind die Masterdaten des persons (Personen) - Moduls. Es sind nicht die Masterdaten einer einzelnen Person. Dann wäre es konsistent zu persons/properties, welches Eigenschaften des persons liefert.

Da sind wir dann unterschiedlicher Meinung. Für mich ist an der Stelle person ein Domain Type und der ist erstmal in der Einzahl außer es handelt sich um mehrere. Da geht es um das Konzept der Person und nicht um eine oder viele.

Und ja ich stimme dir zu, dass naming wehr wichtig ist.

bwl21

@davidschilling

@davidschilling sagte in Benennungen der API manchmal nicht ganz konsistent:

Da sind wir dann unterschiedlicher Meinung. Für mich ist an der Stelle person ein Domain Type und der ist erstmal in der Einzahl außer es handelt sich um mehrere. Da geht es um das Konzept der Person und nicht um eine oder viele.

Ja das kann ich nachvollziehen und ändere da gerne (meine ohnehin nur mäßg relevante) Meinung. Danke für die Erläuterung.

Dann müsste man vielleicht auch masterdata/person zu person/masterdata/roles machen.