gemma-zaken
gemma-zaken copied to clipboard
VNG-Realisatie
As a team member, I want the APIs to support version negotation
so that we can handle minor version releases at the same time.
Currently we're in an odd situation where all APIs are at version 1.0.0 (release candidate). Version negotiation via HTTP Headers is not relevant yet. However, a couple of 1.1 features are very close to "release" (for at least the test environments), and we should implement this version negotiaton.
Required functionality:
- [ ] Implement a version negotiator. We can look at the content-type negotiator in DRF for inspiration
- [ ] Ability to mark features with a certain version (range). E.g., in DRC, we want to mark an entire viewset as "available from 1.1", whereas some other codepaths are more granular. Another example is the
ETagheaders and conditional requests - thoses should also be put behind a 1.1 feature flag. I'm thinking decorators for this.
Onderstaande "vink-lijst" is voor het team zelf om in te vullen en hoeft niet door de indiender te worden ingevuld.
Bepaling prioriteit door PO
- [ ] verbreding of verdieping API's
- [ ] stimuleert gebruik door gemeenten
- [ ] stimuleert gebruik door leveranciers
... eventueel nog toelichting door PO
Definition of ready
- [ ] Iedereen in het team begrijpt de user story
- [ ] de gewenste (aanvulling op de) functionaliteit van de API's duidelijk en beschreven is.
- [ ] Is klein genoeg (maximaal 1/5 van sprint)
- [ ] Product Owner akkoord en voorzien van prioriteit (mag alleen afgevinkt worden door PO)
- [ ] Idee hebben van hoe deze user story kan worden gedemonstreerd.
- [ ] Globale oplossingsrichting bekend
- [ ] Vastgelegd in Github en geplaatst in kolom ready
Definition of done
- [ ] Er is een OAS 3.0 specificatie
- [ ] Er is een referentieimplementatie
- [ ] Er zijn tests(cases) aanwezig die de wijziging aantonen en waarmee de user story getest kan worden.
- [ ] De technische specificatie (standaard.md) is gepubliceerd leesbaar
- [ ] Gebruikte gegevensmodel is na iedere sprint bijgewerkt.
Acceptatiecriteria
- [ ] De DSO URI- en API-strategie worden gevolgd of afwijkingen zijn vastgelegd als ontwerp keuze
- [ ] Er zijn geen bekende GEMMA tegenstrijdigheden of afwijkingen zijn vastgelegd.
Taken
- [ ] Implementeren in referentie-implementatie [verantwoordelijke]
- [ ] Schrijven (unit) test voor referentie-implementatie [verantwoordelijke]
- [ ] Genereren/opstellen van OAS 3.0 [verantwoordelijke]
- [ ] Human Readable publiceren Open API Specificatie (v.3.0) [verantwoordelijke]
- [ ] Documentatie bijwerken
- [ ] Gegevensmodel bijwerken
so that we can handle minor version releases at the same time
@sergei-maertens "at the same time" means with the same instance or codebase?
Ach, ik dacht al dat er een user story voor was, maar kon hem niet terugvinden. Dank voor het linken!
"at the same time" means with the same instance or codebase?
Same instance and same codebase.
See: https://github.com/Geonovum/KP-APIs/blob/master/Werkgroep%20API%20strategie/Designrules%20v1.0.md#versioning
In die tekst staat dat er ook kan worden doorgelinkt naar andere omgevingen zoals preproductie/acceptatie.
@joeribekker vraag: maakt implementatie hiervan de versienummers in de url overbodig?
@joeribekker maakt een voorstel voor de oplossing en @HenriKorver reviewt.
Het is niet verstandig om in deze fase een oplossing te maken omdat andere API's dit weer op een andere manier gaan oplossen. Moet centraal vanuit landelijke API-strategie of vanuit VNG Realisatie/architectuur worden opgelost.