You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jun 30, 2021. It is now read-only.
- beide `pagingStrategy` waardes (`noCount` en `withCount`) moeten ondersteund worden
184
+
211
185
### Event resources
212
186
213
187
POST [/\<groepering>]*/\<event> waarbij \<event> eindigt op een voltooid deelwoord
@@ -669,7 +643,7 @@ Stel dat contract 42 van business party 6532 volgende resource representatie hee
669
643
"value": 850
670
644
}
671
645
}
672
-
```
646
+
```
673
647
en je wil de prijs veranderen naar 950 Euro,<br/>
674
648
dan kan je dit als volgt doen
675
649
@@ -684,7 +658,7 @@ met als request body
684
658
"value": 950
685
659
}
686
660
}
687
-
```
661
+
```
688
662
689
663
690
664
#### DELETE
@@ -847,36 +821,51 @@ Dit geeft als resultaat een lijst van business parties aflopend volgens zip code
847
821
848
822
Paginatie informatie wordt **steeds** terug gegeven bij het ophalen van collections. Dit om er voor te zorgen dat collections die in eerste instantie een beperkt aantal entiteiten bevatten op termijn te groot kunnen worden om de vooropgestelde performantie te kunnen blijven garanderen.
849
823
850
-
Vanuit consumer standpunt is het noodzakelijk dat deze volgende informatie in de response terugkrijgt om voldoende informatie te bekomen rond de pagina's:
824
+
Vanuit consumer standpunt is het noodzakelijk dat volgende informatie in de response wordt gegeven om voldoende informatie te bekomen rond de pagina's:
|| Totaal aantal elementen | Afhankelijk van pagingStrategy |
836
+
|| Totaal aantal pagina's | Afhankelijk van pagingStrategy |
851
837
852
-
- Link naar de eerste pagina
853
-
- Link naar de laatste pagina
854
-
- Link naar de vorige pagina
855
-
- Link naar de volgende pagina
856
-
- Extra metadata:
857
-
- Huidig paginanummer
858
-
- Aantal resources per pagina
859
-
- Totaal aantal resources
860
-
- Totaal aantal pagina's
861
838
862
-
De informatie kan eenvoudig en efficiënt worden berekend in de back-end systemen en verlicht de verwerking langs consumer kant.
839
+
840
+
In veel paginatierichtlijnen wordt gevraagd om het totaal aantal pagina's en/of elementen altijd terug te geven zodat de gebruiker exact kan geïnformeerd worden over de lengte van de opgevraagde lijst. Dit houdt in dat er impliciet altijd een 'count' mechanisme moet geïmplementeerd worden wat bij lijsten van grote aantallen tot een merkbare vertraging kan leiden in het opvragen van de lijst.
841
+
842
+
Daarom kiezen we met onze API requirements voor een oplossing die 2 strategieën implementeert :
843
+
- een snellere opvraging zonder verplichte 'count'
844
+
- een potentieel tragere opvraging tengevolge een impliciet 'count'-mechanisme
845
+
846
+
De client toepassing kiest welke strategie wordt toegepast dmv van een (optionele) query parameter : **`pagingStrategy`** (zie verder).
863
847
864
848
### Paginatie query parameters
865
849
866
-
Het ophalen van een bepaalde pagina zelf dient te gebeuren door middel van de **`page`** en **`pagesize`** query parameters.
850
+
Het ophalen van een bepaalde pagina zelf dient te gebeuren door middel van de **`page`** en **`pagesize`** query parameters (behalve voor de `last` link bij `pagingStrategy=noCount`, zie verder).
867
851
```prettyprint
868
852
/partners?page=1&pagesize=10
869
853
```
870
854
871
-
Paginatie queries starten steeds met *page=1*
855
+
Paginatie queries starten steeds met *page=1*, niet 0. De keuze hiervoor is gemaakt op basis van gebruiksvriendelijkheid naar de API consumer en gebruiker toe.
872
856
873
-
De keuze hiervoor is gemaakt op basis van gebruiksvriendelijkheid naar de API consumer toe.
874
-
875
-
De paginatie query parameters zijn **optioneel**. Dat maakt dat indien deze niet zijn opgegeven:
857
+
De paginatie query parameters zijn **optioneel**. Dat maakt dat wanneer deze **niet** zijn opgegeven:
876
858
877
859
- Een beperkte set van resources wordt teruggegeven bij het bevragen van collections op basis van een default page size die voor elke API wordt bepaald.
878
860
- Steeds de eerste pagina wordt terug gegeven.
879
861
862
+
Om de paging strategie mee te geven, gebruikt de consumer de optionele parameter **`pagingStrategy`**. Deze heeft 2 mogelijke waardes :
863
+
- withCount (default als de query parameter niet wordt meegegeven)
864
+
- noCount
865
+
866
+
Bij **`withCount`** worden __`Totaal aantal elementen`__ en __`Totaal aantal pagina's`__ altijd verplicht terug gegeven. Bovendien bevat de __`link naar de laatste pagina`__ het paginanummer (zie verder voor een voorbeeld).
867
+
Bij **`noCount`** worden de beide totalen niet terug gegeven en is de link naar de laatste pagina een link zonder paginanummer met de vermelding **`last`** (zie verder voor een voorbeeld).
868
+
880
869
### Paginatie response bericht
881
870
882
871
Om paginatie informatie naar de consumer terug te sturen baseren we ons op de HAL specificatie:
@@ -951,17 +940,29 @@ Dit resulteert in volgende structuur.
951
940
```
952
941
953
942
Het **\_page** reserved keyword vormt geen onderdeel van de HAL specificatie, maar is extra metadata die in de response message komt om
954
-
een indicatie te krijgen van de huidige paginanummer, aantal elementen per pagina, het totaal aantal pagina's en het totaal aantal elementen en vereenvoudigt de bewerkingen langs consumer kant om deze informatie te bekomen.
943
+
een indicatie te krijgen van de huidige paginanummer, aantal elementen per pagina, het totaal aantal pagina's en het totaal aantal elementen en vereenvoudigt de bewerkingen langs consumer kant om deze informatie te bekomen. Bij **`pagingStrategy=noCount`** worden `totalElements` en `totalPages` weg gelaten.
944
+
945
+
Voorbeeld bij `pagingStrategy=withCount` :
955
946
```json
956
947
{
957
948
"_page": {
958
949
"size": 10,
959
950
"totalElements": 73853,
960
951
"totalPages": 7386,
961
952
"number": 1
953
+
}
962
954
}
955
+
```
956
+
957
+
Voorbeeld bij `pagingStrategy=noCount` :
958
+
```json
959
+
{
960
+
"_page": {
961
+
"size": 10,
962
+
"number": 1
963
+
}
963
964
}
964
-
```
965
+
```
965
966
966
967
Alle aspecten van paginatie samenvoegend geeft dit volgende response wrapper message voor paginatie:
967
968
```json
@@ -997,13 +998,15 @@ Alle aspecten van paginatie samenvoegend geeft dit volgende response wrapper mes
997
998
}
998
999
}
999
1000
```
1001
+
1002
+
Zoals reeds vermeld vallen `totalElements` en `totalPages` weg bij `pagingStrategy=noCount`.
In de **last** link wordt gebruik gemaakt van **page=last** ipv het exacte paginanummer om te vermijden dat een count moet uitgevoerd worden bij het ophalen van de lijst. Dit houdt wel impliciet in **dat de API deze waarde (=last) ook verplicht moet ondersteunen**. Pas wanneer deze wordt gebruikt zal de API een count uitvoeren om op dat moment de laatste pagina te berekenen en terug te geven.
1081
+
1082
+
Een API moet altijd beide `pagingStrategy` methodes ondersteunen.
1083
+
1041
1084
**Bij het ophalen van een collection zonder specificatie van query parameters dient paginatie informatie altijd aanwezig te zijn in de
1042
-
response message**.
1085
+
response message**, gebruik makend van de `withCount` paginatie strategie.
1043
1086
Het aantal elementen dat in zulk geval wordt teruggegeven (page size) is API specifiek en dient te worden bepaald tijdens de API design fase.
1044
1087
1045
1088
## Event resources
@@ -1172,7 +1215,7 @@ In sommige gevallen kan het nuttig zijn om **extra info** mee te geven zodat de
0 commit comments