Vermijd een directe koppeling tussen definitie en structuur in een gegevenswoordenboek en een API

[melsk-r]

Er is geen directe koppeling tussen de definitie en structuur van gegevens in een gegevenswoordenboek (informatiemodel) en de definitie en structuur van de corresponderende resource en/of property in een API.

Voorbeelden:

• Een resource mag meer gegevens bevatten dan het corresponderende object uit het gegevenswoordenboek. Er mogen bijvoorbeeld gegevens uit gerelateerde objecten aan de resource worden toegevoegd. Bijvoorbeeld bij een nummeraanduiding wordt de woonplaatsnaam opgenomen.
• Een resource mag minder gegevens bevatten dan het corresponderende objecttype. In de resource worden alleen gegevens opgenomen waar behoefte aan is bij de gebruikers van de API.
• Verschillende elementen uit het object mogen worden samengevoegd tot éen property van de resource. Bijvoorbeeld aanschrijfwijze is samengesteld uit o.a. voornamen, tussenvoegsel en geslachtsnaam.
• Een element uit een model mag worden opgesplitst in meerdere properties in de resource. Bijvoorbeeld een mogelijk onbekende overlijdensdatum kan worden opgenomen als overlijdensdatum én indicatieOverleden.
• Een abstract objecttype mag als (concrete) resource worden gedefinieerd. Bijvoorbeeld adresseerbaar object wordt resource adresseerbareObjecten.
• Gegevens uit verschillende (gegevens)groepen mogen worden platgeslagen in de resource of in een gegevensgroep. Bijvoorbeeld Gemeente van inschrijving uit groep Inschrijving, functie adres uit groep Verblijfplaats en postcode uit groep Adres worden opgenomen in verblijfplaats.
• Een resource mag gegevens opnemen in een andere representatievorm.
  • Bijvoorbeeld Indicatie geheim kan de waarden 0 (niet geheim) of 7 (geheimhouding) hebben in het informatiemodel, maar in de API wordt dit opgenomen als boolean.
  • Bijvoorbeeld enumeratie Type openbare ruimte wordt opgenomen als string, wanneer deze waarde alleen voor mensenogen bedoeld is en niet door computercode geïnterpreteerd hoeft te worden.

Ratio:

• Koppeling met de implementatie van de providerregistratie beperkt de evolvability van zowel de achterliggende systemen, als van de applicaties die de API gebruiken, als van de API zelf.
• Ontwerp van de resource gericht op de informatiebehoefte en het gebruik is eenvoudiger in gebruik en verkleint de kans op verkeerd gebruik.

[melsk-r]

JBo: Discussie
HK:
RM: Zie opmerking
MV: Discussie
GJ: Niet overnemen.
JBi: Niet overnemen. Eens met commentaar JBo en MV

JBo: M.i. zit hier de rol van het uitwisselingsmodel. Ik denk ook dat deze DD minder opgaat voor systeem-API's (alhoewel je dan ook een gegevensmodel gemaakt moet hebben.)
MV: Dit lijkt ook te pleiten voor meerdere UGM's voor een CIM. Bijvoorbeeld een vrij plat UGM om systeem API's te definiëren en een ander UGM voor experience en process API's waar gegevens uit resources in gecombineerd kunnen worden.
RM: De eerste regel van deze DD zou ik wijzigen in 'De definitie en structuur van gegevens in een gegevenswoordenboek (informatiemodel) en de definitie en structuur van de corresponderende resource en/of property in een API mogen van elkaar afwijken.'