REST Design überdenken und einheiltlich aufbauen/erweitern/ändern

[darenegade]

Siehe: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

[peter-mueller]

Das API Design ist mir teilweise unklar:

• New Buerger

    @RequestMapping(value = "/new", method = {RequestMethod.GET})
    public ResponseEntity newBuerger() {
        ...
    }

  Wieso kein POST als create mit allen Infos des neuen Bürgers?

• List Delete

  @RequestMapping(value = "/delete", method = {RequestMethod.POST})
  public ResponseEntity deleteListBuerger(@RequestBody ArrayList<String> oids) {
    ...
  }

  Wieso ist das notwendig? Warum auf "/buerger/delete". z.B. /buerger?oids=1,2,3 mit RequestMethod.DELETE

• Add Relation

  @RequestMapping(value = "/add/buerger/{bOid}/kind/{kOid}", method = {RequestMethod.GET})
  public ResponseEntity addKindBuerger(@PathVariable("bOid") String buergerOid, @PathVariable("kOid") String kindOid) {
    ...
  }

  Es wird doch eine Beziehung erstellt wieso kein POST auf .../kind mit kOid als RequestBody. Hier gibt es auch ein Problem bei HATEOAS: Wie soll der Link generiert werden?

[peter-mueller]

• Query

  @RequestMapping(value = "/query", method = {RequestMethod.POST})
  public ResponseEntity queryBuerger(@RequestBody String query) {
    ...
  }

  /buerger?query={{query}} mit GET

• copy buerger garnicht notwendig?
• update mit PUT (und partiell mit PATCH)
• "release/relation" mit DELETE auf /buerger/kinder/{oid}

[xdoo]

Zu New:

In Java hast du die Struktur. In JS beispielsweise nicht unbedingt. Über New bekommst du die Struktur.

Zu delete:

Der Zusatz 'delete' ist nicht notwendig. Bitte die URL so schneiden /buerger/. Bitte keine ? Parameter.

Zu Beziehung:

Ja, die OID des Kindes gehört in die Payload.

[xdoo]

Query:

Bitte so lassen. Parameter in der URL musst du escapen. Was ist schlecht an Post im Body?

Copy:

Warum braucht man copy nicht? Wo willst du das sonst machen?

Update:

Put ist OK.

[xdoo]

Release relation:

Wäre mit delete OK. Ich denke nur, dass man da irgendwo eine oder n OIDs braucht.

[peter-mueller]

• Copy entspricht doch einem GET und einem POST (create), warum die API aufblähen?
• Query ist geschmackssache, ich kenne es so das GET alle Objekte gibt und mit @RequestParam = ? gefiltert wird

[peter-mueller]

• Das (listen-) delete von mehreren Objekten ist meiner Meinung nach auch nicht notwendig.

[xdoo]

Ein copy ist ein get, kopieren und Post. Natürlich kann man das alles auf der Oberfläche machen, aber ich finde es im Service ganz aufgeräumt :)

[xdoo]

Wie gesagt: bei query und URL Parameter hast du immer ein escape Problem, das du bei Post so nicht hast. Der Nachteil ist natürlich, dass man mit Post keine such URLs hast, die du beispielsweise verschicken kannst.

[xdoo]

Ein Multi Delete brauchst du, wenn du in einer grid Komponente mehrfach Auswahl zu lässt. Ansonsten machst du n Einzel requests.

[peter-mueller]

Not only are the items and their prices shown, but the URL for each resource is shown, providing clear information on how to access these resources. According to the Richardson Maturity Model, HATEOAS is considered the final level of REST. This means that each link is presumed to implement the standard REST verbs of GET, POST, PUT, and DELETE (or a subset). Thus providing the links as shown above gives the client the information they need to navigate the service.

Spring HATEOAS

Die Änderung (z.B.) mit DELETE würde dann auch das entfallen einiger Relations bedeuten:

if (relations.contains(HateoasUtil.REL_DELETE)) {
            resource.add(linkTo(methodOn(BuergerController.class).deleteBuerger(buerger.getOid())).withRel(HateoasUtil.REL_DELETE));
        }

Hier genügt dann die Relation "self" da DELETE ja Konvention ist.

Ist das so O.K./gewollt?

[xdoo]

Ich würde sagen, das ist Geschmacksache. Man kann natürlich eine Ressource wie

http://localhost/buerger/47AFrt*7465

nehmen und mit self referenzieren. Die ganzen Dinger GET, POST, PUT, DELETE sind dann automatisch drin. D.h. im Rest Client müssen wir dann nur nach der Self Relation suchen. Der Nachteil, den ich sehe (der aber bei der Generierung keine Rolle spielt, weil das alles automatisch heraus purzelt) ist, dass jemand der programmatisch an die REST API ran geht und nicht so fit mit HATEOAS ist (also 99% der Leute bei der LHM) und diese "versteckten" Operationen nicht checkt.

Da wir aber eh generieren, würde ich das "LHM know how Problem" aber mal ignorieren und die reine Lehre implementieren.

[peter-mueller]

62 Möglichkeit 2

[darenegade]

@peter-mueller Wenn Änderungen am Rest Design umgesetzt werden, dann sollten auch immer alle in dem Zusammenhang stehenden Funktionen (Service Anfragen in der GUI) mit angepasst werden!

[peter-mueller]

Von mit gibt es keine Änderung am REST Design im master. Ich versuche generell immer im merge mit dem master das Ticket zu referenzieren damit der commit von mir hier angezeigt wird.

~~Bitte die beiden Nachrichten wieder löschen weil das nichts mit dem Ticket zu tun hat.~~

[darenegade]

Eine Änderung am Rest Design (dieses Ticket) steht immer im Zusammenhang mit den Auswirkungen auf andere Systeme. Somit gehört dies definitv zu diesem Ticket. Lass uns das einfach am Montag in persona klären. ;)

[darenegade]

Ein Upgrade von Spring Sec3 auf Spring Sec4 löst das Permissions Problem, da Sec4 den "ROLE_" Prefix automatisch vor eine Authority setzt. Hier ein guter und ausführlicher Beitrag zu dem Thema: http://stackoverflow.com/questions/19525380/difference-between-role-and-grantedauthority-in-spring-security