Vragen en opmerkingen m.b.t. de eerste tabel in paragraaf '3.2 HTTP methods'

[melsk-r]

De eerste tabel in paragraaf '3.2 HTTP methods' roept wat vragen/opmerkingen bij me op, en niet bij mij alleen heb ik ondervonden.

1. De zin 'Create a subresource as part of a collection resource.' kan je eigenlijk alleen goed begrijpen als je weet wat een 'collection resource' is.
   Ik denk dat ik het nu begrijp maar alleen omdat ik grondig door het document heen en weer ben gegaan, daarin overal heb gezocht naar dit begrip en alles wat er over gezegd wordt tot me heb genomen.
   Het lijkt me goed om van de term 'collection resource' in de tabel een link te maken naar een locatie in dit document waar dit uitgelegd wordt.
   De aard van het document maakt nl. dat je het niet sequentieel doorneemt maar springt van locatie naar locatie. Dat betekent dat je er als schrijver op verdacht moet zijn dat de uitleg van een begrip nog niet de revue heeft gepasseerd bij de lezer.
   Die uitleg kan wat mij betreft ook nog wel wat beter en moet denk ik vergezeld gaan van een goed voorbeeld. Overigens zou de bewuste zin volgens mij als volgt moeten zijn 'Create a subresource as part of a (sub)collection resource.'

2. Daarnaast wekte de zin 'This operation is not relevant for singular resources.' in de beschrijving van de POST method wat bevreemding op.
   Zeker omdat de daaraan voorafgaande zin 'Create a subresource as part of a collection resource.' luidt en paragraaf '3.1 Resources' de zin 'Collection resources typically contain references to the underlying singular resources.' bevat.
   
   Daaruit trek ik de volgende conclusies:

   • Met een POST maak je dus een subresource van een collections resource aan;
   • Een collection resource bevat references naar de onderliggende singular resources (en dus subresources);
   • Maar met een POST mag je geen singular resources creëren.

   Buiten het feit dat wij niet begrijpen waarom je met een POST geen singular resource zou mogen aanmaken lijken deze bullets in tegenspraak met elkaar.

3. Mag de url van een singular resource die geen onderdeel is van een collection resource nooit een identifier bevatten (dus alleen zoiets https://api.example.org/v1/gebruikersprofiel) of mag dat wel (dus ook zoiets https://api.example.org/v1/gebruikersprofiel/d285e05c-6b01-45c3-92d8-5e19a946b66f)?
   Hoe weet je, indien het wel mag, dat het niet om een collection resource gaat? Alleen omdat het deel van de url voor de identifier in singular form is geschreven?
   Wat voorkomt, in dat geval, dat een singular resource niet ineens in een collection resource wordt opgenomen door een nieuwe POST te doen naar bijv. https://api.example.org/v1/gebruikersprofiel?

4. Er staat 'Resources can also be grouped into collections'. Mag je, aangezien een 'Collection resource' ook een resource is, de conclusie trekken dat een 'Collection resource' ook andere 'Collection resources' kan bevatten? Of wordt dat met de zin 'Collection resources typically contain references to the underlying singular resources.' ingeperkt?

[TimvdLippe]

Hier heeft @joostfarla in #239 een verscherping op gedaan. Komen die definities meer in de buurt die we ook in de tabel moeten zetten?

[TimvdLippe]

@melsk-r Graag reactie op bovenstaand comment.

[melsk-r]

Ad 1. De uitleg lijkt me beter maar ik vermoed dat ik, als ik nu nog de kennis had die ik in augustus had, nog steeds eerst alles wat in het document gezegd wordt over collection resources tot me zou hebben moeten nemen om het goed te begrijpen. Niet omdat de term 'collection resource' niet wordt uitgelegd voor de in dit punt aangehaalde zin (iets wat je n.a.v. de door mij gemaakte opmerkingen zou kunnen concluderen) maar omdat de informatie die na deze zin in dit document wordt gegeven blijkbaar toch nog iets toe heeft gevoegd aan mijn begrip.

De bewuste zin is overigens nog niet aangepast naar 'Create a subresource as part of a (sub)collection resource.'

Ad 2. N.m.m. zijn de vragen die ik hier stel nog niet beantwoord. Ik vermoed dat er een belangrijk nuanceverschil zit tussen een subresource en een singular resource.

Ad 3. Ook deze vraag is nog niet beantwoord.

Ad 4. Idem. Betreft het hier subcollection resources?