Releasenotes NLGov REST API Design Rules versie 2.0.0 (ADR2)
De standaard REST API Design Rules geeft een brede verzameling functionele en technische regels voor structuur en naamgeving waarmee de overheid op een uniforme en eenduidige manier veilige REST-API's aanbiedt. Dit maakt het voor ontwikkelaars gemakkelijker om betrouwbare applicaties te ontwikkelen met API's van de overheid. ADR2 sluit nauw aan bij de modulaire opbouw van het Kennisplatform API's en bevat nu ook regels voor Transport Security & Geospatial API's. Naast al deze aanvullingen is ook de opmaak en structuur van de regels verbeterd voor een eenduidige gebruikservaring.
Inleiding
Op 09-07-2020 is besloten om versie 1.0 van de API Design Rules "Verplicht" te stellen op de lijst van open standaarden van het forum standaardisatie. zie ook https://forumstandaardisatie.nl/open-standaarden/rest-api-design-rules
In samenwerking met het Kennisplatform APIs is in 2022 & 2023 gewerkt om de designrules modulair op te zetten, nauw te verbinden met de tests op developer.overheid.nl en verschillende kleine verbeteringen door te voeren. Deze werkzaamheden hebben geleid tot deze nieuwe ADR2
- Voor ADR2 heeft reeds een publieke consultatie plaatsgevonden van 06-10-2023 tot 06-11-2023.
- ADR2 is door het PGDI goedgekeurd op 07-03-2024 en vastgelegd als besluit 83.
- ADR2 is op 25-01-2024 aangemeld bij het Forum Standaardisatie voor opname op de lijst als nieuwe versie.
Samenvatting wijzigingen
De wijzigingen in versie 2.0.0 zijn zowel technisch als inhoudelijk. Hieronder zijn de belangrijkste wijzigingen samengevat:
- Technisch:
- het "API Design Rules" document is bijgewerkt naar Respec versie 34
- de publicatie van de standaard is verplaatst naar de uri "https://gitdocumentatie.logius.nl/"
- het overzicht van rules wordt gegenereerd en is gesplitst in functionele en technische rules
- rules hebben een type (Functional/Technical), op basis hiervan wordt de implication gegenereerd
- de Semantic versioning rule is uitgebreid met pre release opties
- Functioneel:
- de algemene API Strategie Infographic is opgenomen in de bijgewerkte inleiding
- de nummering van de design rules is vervangen door logische namen
- alle rules zijn nu beschreven op basis van het Togaf template voor Principes (Name, Statement, Rationale, Implications)
- bij de technical type rules is een "how tot test" beschrijving opgenomen en een verwijzing naar het test script van developer.overheid.nl
- De module "Transport Security" is verplicht gesteld in par 3.8 voor alle APIs
- De module "Geospatial" is is verplicht gesteld in par 3.9 voor alle APIs met geospatial data of functies
What's Changed
- Typo fixes by @jarichypma in #1
- issue #19 verwerken in Design rules by @jasperroes in #2
- Typo aangepast by @jasperroes in #3
- Typo's en issues verwerkt by @jasperroes in #4
- Issue #162 opgelost by @jasperroes in #5
- Inline rules + summary by @joostfarla in #7
- Create publishers.yml by @mrtn78 in #122
- Statement, Rationale, Implications by @sanderke in #121
- gitdocumentatie by @logius-standaardenbeheer in #127
- Adr validator links bijgewerkt by @mrtn78 in #125
- reference to ADR beheermodel added by @mrtn78 in #124
- [API-56] Clarify use of pre-release versions by @joostfarla in #123
- Omnummeren design rules by @joostfarla in #128
- Update DesignRules.md by @mrtn78 in #131
- update rule API-03 by @mrtn78 in #130
- Mrtn78 patch verduidelijken inleiding by @mrtn78 in #129
- update branche to stay in sync with develop by @mrtn78 in #132
- Improvement API-03 (HTTP methods) by @strijm in #133
- Added GEO section and rule by @mrtn78 in #137
- Update README.md by @mrtn78 in #139
- Verdieping testen by @mrtn78 in #134
- Redactioneel commentaar verwerkt by @sanderke in #140
- Added a conditional TLS module rule by @mrtn78 in #138
- Copy/paste vermindering by @sanderke in #142
- Aanpassingen mbt werkingsbieden by @joostfarla in #143
- Publicatie van ADR 2 naar de main branche by @mrtn78 in #144
- links bijgewerkt naar rules.go v0.5.0 by @mrtn78 in #145
- Publicatie van ADR 2 Versie ter vaststelling naar de main branche by @mrtn78 in #146
- PR:ADR_2.0.0_Release by @mrtn78 in #148
- Update SOTD.md by @mrtn78 in #149
New Contributors
- @jarichypma made their first contribution in #1
- @jasperroes made their first contribution in #2
- @joostfarla made their first contribution in #7
- @sanderke made their first contribution in #121
- @logius-standaardenbeheer made their first contribution in #127
- @strijm made their first contribution in #133
Full Changelog: 2.0.0...v2.0.0
