-
Notifications
You must be signed in to change notification settings - Fork 7
/
uri-templating.feature
129 lines (116 loc) · 8.58 KB
/
uri-templating.feature
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# language: nl
Functionaliteit: URI templating
Als API provider
wil ik uri templating kunnen gebruiken
zodat grote aantallen links naar dezelfde API in de response kunnen worden gerepresenteerd door één URI template
zodat ik geen url's naar externe API's hoeft te beheren
Zoals gespecificeerd in RFC 6570 (https://tools.ietf.org/html/rfc6570):
- Een URI template is een string die 0 of meer expressies bevat, waarmee een verzameling van URI's kan worden beschreven
- Een expression is de tekst tussen een open accolade '{' en een sluit accolade '}' inclusief de accolade tekens
- Expanden van een template is het vervangen van een expression door een waarde.
De manier van expanden wordt bepaald door een optionele operator in de expression. Voor meer info zie: [Expressions](https://tools.ietf.org/html/rfc6570#section-2.2)
Op het moment van specificeren (18-05-2020) wordt in de Haal Centraal API's alleen de meest simpele 'Simple String Expansion' expression gebruikt,
een {expression} wordt vervangen door een variabele
Afspraken:
- gebruik {[xxx]serverurl} als placeholder voor de server url van externe API url's
[xxx] is de afkorting die wordt gebruikt voor de externe API.
Op het moment van specificeren worden de volgende serverurl placeholders gebruikt in de Haal Centraal API's:
- {brpserverurl}
- {bagserverurl}
- {brkserverurl}
- {hrserverurl}
- gebruik {propertynaam} als placeholder in een resource path. propertynaam is:
- de naam van een property van de resource of
- de naam van een property van een gegevensgroep van de resource.
Gebruik in dit geval de naam van de gegevensgroep gevolgd door een punt als prefix, bijv. persoon.identificatie, woonadres.adresIdentificatie
- indien de lijst met identificaties, die gebruikt wordt om samen met de templated link de daadwerkelijke links op te bouwen, leeg is wordt de templated link niet opgenomen.
- indien een resource (via gegevensgroepen) meerdere verwijzingen heeft naar een zelfde resource type, dan kan voor deze verwijzingen één link property worden gedefinieerd.
Scenario: Verwijzing naar één externe Resource
Gegeven een KadastraalOnroerendeZaak heeft een verwijzing via de 'adresIdentificatie' property naar een Adres
En een Adres is te bevragen bij de BAG API via endpoint '/adressen'
Als een templated Hal link voor de Adres is gegenereerd
Dan is de Hal link naar de Adres gelijk aan
| href | templated |
| {bagserverurl}/adressen/{adresIdentificatie} | true |
Scenario: Verwijzing naar één externe Resource via gegevensgroep property
Gegeven een KadastraalOnroerendeZaak heeft een verwijzing via de 'adresIdentificatie' property van gegevensgroep 'woonadres' naar een Adres
En een Adres is te bevragen bij de BAG API via endpoint '/adressen'
Als een templated Hal link voor de Adres is gegenereerd
Dan is de Hal link naar de Adres gelijk aan
| href | templated |
| {bagserverurl}/adressen/{woonadres.adresIdentificatie} | true |
Scenario: Verwijzingen naar meerdere externe Resources van dezelfde soort
Gegeven een KadastraalOnroerendeZaak heeft een verwijzing via de 'adresIdentificaties' property naar meerdere Adressen
En een Adres is te bevragen bij de BAG API via endpoint '/adressen'
Als een templated Hal link voor de Adressen is gegenereerd
Dan is de Hal link naar de Adressen gelijk aan
| href | templated |
| {bagserverurl}/adressen/{adresIdentificaties} | true |
Scenario: Verwijzing naar verschillende externe en interne Resources
Gegeven een ZakelijkGerechtigde heeft een verwijzing via de 'identificatie' property naar een Ingeschreven Natuurlijk Persoon
En een Ingeschreven Natuurlijk Persoon is te bevragen bij de BRP API via de endpoint /ingeschrevenpersonen
En een ZakelijkGerechtigde heeft een verwijzing via de 'identificatie' property naar een Ingeschreven Niet Natuurlijk Persoon
En een Ingeschreven Niet Natuurlijk Persoon is te bevragen bij de BRK via de endpoint /kadasternietnatuurlijkpersonen
Als een templated Hal link voor de Personen is gegenereerd
Dan is de Hal link naar de Persoon van het type ingeschreven_natuurlijk_persoon gelijk aan
| href | templated |
| {brpserverurl}/ingeschrevenpersonen/{identificatie} | true |
En is de Hal link naar de Persoon van het type ingeschreven_niet_natuurlijk_persoon gelijk aan
| href | templated |
| {brkserverurl}/kadasternietnatuurlijkpersonen/{identificatie} | true |
Scenario: Verwijzingen naar een Resource type via meerdere properties van één of meerdere gegevensgroepen
Gegeven een ZakelijkGerechtigde met de volgende kenmerken
| naam | waarde |
| zakelijkRecht.stukIdentificaties | 1234567 |
| zakelijkRecht.isVermeldInStukdeelIdentificaties | 2345678 |
| tenaamstelling.stukIdentificaties | 3456789 |
| tenaamstelling.isVermeldInStukdeelIdentificaties | 4567890 |
Als de ZakelijkGerechtigde wordt geraadpleegd
Dan bevat de response de volgende kenmerken
| naam | waarde |
| _links.stukken | {brkserverurl}/stukken/{stukIdentificatie} |
| _links.stukdelen | {brkserverurl}/stukdelen/{stukdeelIdentificatie} |
En kan het stuk met identificatie 1234567 worden geraadpleegd met uri '{brkserverurl}/stukken/1234567'
En kan het stuk met identificatie 3456789 worden geraadpleegd met uri '{brkserverurl}/stukken/3456789'
En kan het stukdeel met identificatie 2345678 worden geraadpleegd met uri '{brkserverurl}/stukdelen/2345678'
En kan het stukdeel met identificatie 4567890 worden geraadpleegd met uri '{brkserverurl}/stukdelen/4567890'
Scenario: Expanden van een templated url
Gegeven de json response fragment van een kadastraal onroerende zaak
"""
{
"_link": {
"adressen": {
"href": "{bagserverurl}/adressen/{adresidentificaties}",
"templated": true
}
},
"adresidentificaties": [
"0518200000437093",
"0518200000812475"
]
}
"""
En de server url van de BAG API is gelijk aan 'https://api.bag.kadaster.nl/esd/huidigebevragingen/v1'
Als de templated adressen url is ge-expand voor de adresidentificaties
Dan zijn de ge-expande urls
| ge-expande urls |
| https://api.bag.kadaster.nl/esd/huidigebevragingen/v1/adressen/0518200000437093 |
| https://api.bag.kadaster.nl/esd/huidigebevragingen/v1/adressen/0518200000812475 |
Scenario: Uitsluiten van properties die een placeholder functie hebben met de fields parameter
Gegeven een KadastraalOnroerendeZaak heeft een verwijzing via de 'adresIdentificaties' property naar meerdere Adressen
Als met de fields parameter specifieke properties worden opgevraagd
En met de fields parameter de 'adresIdentificaties' property niet wordt opgevraagd
En met de fields parameter de '_links.adressen' property niet wordt opgevraagd
Dan bevat de response geen '_links.adressen' property
Scenario: Meenemen van properties die een placeholder functie hebben bij het opvragen van templated link properties met de fields parameter
Gegeven een KadastraalOnroerendeZaak heeft een verwijzing via de 'adresIdentificaties' property naar meerdere Adressen
Als met de fields parameter de '_links.adressen' property wordt opgevraagd en de 'adresIdentificaties' property niet
Dan bevat de response toch de 'adresIdentificaties' property
Scenario: Meenemen van templated link properties bij het opvragen van properties die een placeholder functie hebben met de fields parameter
Gegeven een KadastraalOnroerendeZaak heeft een verwijzing via de 'adresIdentificaties' property naar meerdere Adressen
Als met de fields parameter de 'adresIdentificaties' property wordt opgevraagd en de '_links.adressen' property niet
Dan bevat de response toch de '_links.adressen' property
Scenario: Geen templated link leveren als de properties die een placeholder functie hebben niet aanwezig zijn (er is geen gerelateerde resource)
Gegeven een KadastraalOnroerendeZaak heeft geen verwijzing via de 'adresIdentificaties' property naar een Adres
Als de KadastraalOnroerendeZaak wordt opgevraagd
Dan bevat de response geen '_links.adressen' property