Frage zu Rest-API-Design

[Der schöne Günther]

Ich biete per Http GET Daten zum Auslesen an.

Für GET http://localhost/api/ bekommt man alles:

Code:

{
   "system": {
      "softwareVersion":  "1.0.0",
      "localClock": "2020-12-31T19:31:00.000"
   },
   
   "control": {
      "isEnabled": true,
      "isInTurboMode": false
   },
   
   "order": {
      "orderNumber": "ABC \/ 123",
      "limits" : {
         "upper": 1.25,
         "lower": 0.8
      }
   }
}

Für GET http://localhost/api/order/limits bekommt man:

Code:

{
   "upper": 1.25,
   "lower": 0.8
}

Soweit noch ganz unspannend.

Nun möchte ich per Http PUT und Http PATCH Änderungen zulassen. Es macht hier nur Sinn bestehendes zu modifizieren, nicht etwas neues hinzuzufügen (daher kein Http POST).


Jetzt stutze ich etwas, was erwartet der typische Benutzer? Angenommen er möchte order/limits/lower ändern.

Mir fallen so viele Dinge ein die man tun könnte:

Code:

Http PATCH http://localhost/api/order/limits

{
  "lower": 0.5
}

oder

Code:

Http PATCH http://localhost/api/

{
  "order": {
    "limits": {
      "lower": 0.5
    }
  }
}

oder

Code:

Http PUT http://localhost/api/order/limits

{
   "upper": 1.25,
   "lower": 0.5
}

oder

Code:

Http PUT http://localhost/api/order/limits/lower

0.5

Was ist das üblichste? Ist das letzte überhaupt gültig?

[sh17]

den Unterschied zwischen PUT und PATCH hast DU ja schon richtig. Hier nochmal erklärt

https://www.predic8.de/post-put-patch-beispiel.htm

Ansonsten wären meiner Meinung nach Deine Beispiel 1 und 3 richtig

[jfheins]

Ich kenne deinen API use-case nicht, aber die Frage stellt sich: Muss man alles ändern können, oder gibt es nur bestimmte Sachen die man ändern kann?

Wenn man nur bestimmte Sachen ändern können soll (lower limit, aber nicht upper limit) dann biete auch nur das an. (Also keinen Patch Endpunkt)

Nebenbei würde ich dir noch GraphQL ans Herz legen, falls das ein guter Fit ist. (Nicht einfach REST nutzen, weil das das erste Projekttemplate ist)

[generic]

Schau dir mal hateos an.


https://m.heise.de/developer/artikel...html?seite=all

[Uwe Raabe]

Zitat von generic:

Schau dir mal hateos an.

Ich dachte erst, das wäre ein neues Betriebssystem - dem allgemeinen Trend folgend

[DeddyH]

Was so ein „a“ nicht alles ausmachen kann

[bernau]

Mit fällt bei REST-Schnittstellen immer mehr auf, dass Swagger als Designtool verwendet wird.

Ist auf jeden Fall mal ein Blick wert.