Richtlijnen voor het bijwerken van (meervoudige) geneste gegevens

[joeribekker]

Om meer gegevens in 1x op te vragen of bij te werken zijn resources soms samengevoegd in een API. Dit is performance-efficient en soms ook handig vanuit transactie-perspectief. Ter illustratie:

GET /boek/9f84bac2-4e65-474a-a230-adfb070f3f15

Geeft een boek terug met 2 auteurs:

{
  "id": "9f84bac2-4e65-474a-a230-adfb070f3f15",
  "titel": "John and Jane",
  "auteur": [{
    "id": "80e08f36-befb-4125-9001-1c92c6fa5968",
    "naam": "John Doe"
   },
   {
    "id": "f7e6430d-fcf1-4052-a0ac-b6366f55fc9a",
    "naam": "Jane Doe"
 }]
}

Als ik dit boek wil aanpassen, kan ik doen:

PUT /boek/9f84bac2-4e65-474a-a230-adfb070f3f15 of PATCH variant

{
  "id": "9f84bac2-4e65-474a-a230-adfb070f3f15",
  "titel": "Johnny and Jane",
  "auteur": [{
    "id": "80e08f36-befb-4125-9001-1c92c6fa5968",
    "naam": "Johnny Doerak"
   }]
}

Duidelijk is dat de titel is aangepast (van John naar Johnny). Maar, de lijst van auteurs is ook gewijzigd. Wat betekent dit? Is de (relatie naar de) auteur "Jane Doe" verwijderd? Is de naam van de 1e auteur gewijzigd naar "Johnny Doerak"? Of heeft het ID enkel gewerkt als een identifier om de relatie naar de auteur te leggen (en wordt de naam genegeerd)?

Algemener: Gaat PUT over het geheel aan gegevens (waardoor het aannemelijker is dat de (relatie naar de) auteur "Jane Doe" is verwijderd, of enkel over het top-level object "boek"? Werkt PATCH op dit vlak anders? Mogen er geen niet-identificerende attributen in PUT/PATCH operaties voorkomen van geneste resources?

We kunnen allemaal een eigen interpretatie hebben van wat het correcte gedrag is, maar juist die discussie zou ik het liefst getackled hebben met een verwijzing naar de API-strategie.

Ik denk dat het goed is om wat richtlijnen te hebben van het typische gedrag van bovenstaande API-call. De OAS-specificatie is niet helder op dit vlak. Uiteraard kan van de richtlijnen afwijken in je specifieke API maar een richtlijn helpt de voorspelbaarheid voor gebruikers en implementatie bij ontwikkelaars.

[mrtn78]

Dit lijkt me een punt wat we kunnen adresseren / oppakken in de nieuwe werkgroep orkestratie van @joostfarla

[sergei-maertens]

Ga vooral spieken wat Kubernetes hier doet, zij hebben best een mooi model voor het toepassen van PATCH in verschillende "operation modes" op basis van de Content-Type header: https://kubernetes.io/docs/reference/using-api/api-concepts/#patch-and-apply