search

Geonovum / KP-APIs

26 stars 40 forks source link

Eager versus lazy loading #276

Open joostfarla opened 4 years ago

joostfarla commented 4 years ago

Placeholder n.a.v. Geonovum/KP-APIs#173. Nader uit te werken...

Dit onderwerp is vorig jaar geschrapt uit het document omdat het nog niet voldoende was uitgekristalliseerd (zie Geonovum/KP-APIs#12, Geonovum/KP-APIs#29 en Geonovum/KP-APIs#71).

mevdschee commented 4 years ago

In mijn ervaring (als maintainer van populaire generieke API implementatie PHP-CRUD-API) is het als je relaties wilt aangeven is het (zoals ook in Geonovum/KP-APIs#12 aangegeven) onvoldoende om de gerelateerde entiteiten te benoemen, maar moet je de relaties (relaterende/fk velden) benoemen.

Voorstel

Stel een "blog" database heeft een "post" met een "auteur" (user) en een "redacteur" (user) en je wilt een "post" met bijbehorende/embedded "user" records opvragen, dan is het belangrijk om de relaties te benoemen. Ook als je bijvoorbeeld de users op de "reacties" (comments) wel of niet wilt embedden of de "maker" (user) van een van de "tags" van een "post". Dan geef je alle paden op naar de te embedden relatie/fk.

Voorbeelden

Embed de "belongsTo" relatie "user" voor "author_user_id"

/posts?embed=author_user_id

Embed de "hasMany" relatie "comments" ("comments" is de naam van een tabel)

/posts?embed=comments

Embed de users van de "hasMany" relatie "comments" (en de comments omdat die in het pad zitten):

/posts?embed=comments.user_id

Embed de users van de "hasAndBelongsToMany" relatie "tags" (en de tags omdat die in het pad zitten):

/posts?embed=tags.creator_user_id

Embed alle users die genoemd zijn:

/posts?embed=author_user_id&embed=editor_user_id&embed=comments.user_id&embed=tags.creator_user_id

Dit zou alle mogelijke gevallen moeten dekken (overigens heet de "embed" parameter in mijn implementatie "join", zie README).

Geleerde lessen

In v1 van mijn generieke API had ik een implementatie waarbij je alleen de te relateren tabellen noemde, maar dat leidde tot problemen (er zijn duizenden developers die deze API gebruiken). Nu heb ik sinds v2 voor bovenstaande model gekozen en sindsdien heb ik geen problemen meer gehoord van mijn gebruikers. Hopelijk helpt het delen van deze ervaring in de besluitvorming.

mevdschee commented 4 years ago

Refenties / achtergronden

In mijn onderzoek naar generieke API implementaties kwam ik de term "automatic-api" tegen en de deze lijst met populaire "automatic-api" software:

https://github.com/dbohdan/automatic-api

Het lezen van de handleidingen (en de issues) van deze software heeft mij veel geleerd over werkbare/onwerkbare oplosingen.

Toekomstig werk

Omdat het gebruik van standaarden in REST en GraphQL ernstig te wensen over laat en de implementatie van (full-featured) REST en GraphQL relatief lastig is, ben ik bezig met een nieuw project:

https://pathql.org

Hiervan zijn al een aantal referentie implementaties beschikbaar.