Versionering van APIs

[skryv-demo]

Nothing is forever... how do we version APIs?

[pietercolpaert]

Ik denk niet dat dit nodig is. Als een generieke client automatisch bouwblokken herkent, en de API wordt geüpdatet, dan zal de generieke client opnieuw de nieuwe bouwblokken kunnen interpreteren.

Meer zelfs: ik denk dat versionering eerder problematisch zou zijn. Het zorgt voor meerdere kanalen voor dezelfde gegevens, en zou dus meer onderhoud vergen.

Andere meningen welkom!

[pietercolpaert]

Het lijkt me wel nuttig, als hier consensus over komt, van dit mee te nemen in de uiteindelijke specificatie.

[pietercolpaert]

Discussie met @bertvannuffelen -- vindt dat we wel een strategie moeten hebben om uitfaseren van API’s aan te kondigen.

[CumpsD]

@pietercolpaert je gaat er dan vanuit dat de enigste consumer van je API een generieke client is, wat zeker niet het geval zal zijn irl. Hoe moeten die dan omgaan met versionering? Je kan niet de burden van generieke clients te bouwen bij alle consumers gaan leggen toch? Sommige gaan gewoon klassiek blijven verder werken.

[pietercolpaert]

Ja, maar deze specificatie gaat niet over hoe je klassiek werkt, maar hoe je net generiek te werk gaat. Deze specificatie zal gerust kunnen worden gecombineerd met bvb. de Burgerloket API specificatie, waarin wel uitspraken worden gedaan over hoe versionering het liefst wordt aangepakt.

[CumpsD]

Dan ben ik niet mee, wat bedoel je met deze specificatie? Is het doel van dit ding niet om een API standaard te worden? Of gaat het enkel over het kleine deeltje van de generieke client? Maw: wat is de scope dan precies van deze oefening?

En hoe combineer je bv item over #14 media types die hier beslist wordt met bv Burgerloket API specificatie als ze tegenstrijdig zouden zijn? Misschien maak ik best een nieuwe issue aan om de scope te discussieren/uitleg over te vragen, laat maar weten.

[pietercolpaert]

Het doel van deze standaard is om enkele bouwblokken af te spreken die over alle API’s van de Vlaamse Overheid gelegd kunnen worden, om te leiden tot automatische integratie. Die scope is mijn inziens okay gedefinieerd in de README.md (gekopieerd uit aankondiging van de opstart van de werkgroep).

Issue #14 zegt in de laatste comment door mij dat één of meer Linked Data representatie, maar timmert niet dicht dat er geen andere representaties mogen zijn. Het versioneren van een API volgens burgerloket API is dan ook niet tegenstrijdig met onze specificatie als wij enkel zeggen “liever niet”, tenzij er ook een specifiekere API is afgesproken die werkt met een nauw contract tussen client en server.

Hier verder daarover discussiëren lijkt me on topic en heel erg eigen aan of we al dan niet versionering oppakken hierin. Gezien de grote interesse van de fysieke werkgroep in deze issue lijkt het me zeker relevant dat we deze hier goed behandelen. Ik ben zelf heel erg op zoek naar een use case waarin dit relevant kan zijn binnen de context van dergelijke generieke bouwblokken die automatisch herkend moeten kunnen worden.

[CumpsD]

Ok, dat is een verduidelijking voor mij.

Even omdraaien ivm de use case: Zijn er nog use cases voor een generieke client buiten de client van http://www.markus-lanthaler.com/hydra/console/?url=http://www.markus-lanthaler.com/hydra/event-api/ ? Om het eens te bekijken van hoe consumers omgaan met een generieke API, en te zien of versionering steek houdt.

Ik vond bv https://github.com/bergos/hydra-core en daaar zie ik deze snippet:

// load the entry point from http://example.com/
hydra.model.load('http://example.com/')
  .then(function (entryPoint) {
    // create a new blog post using the post method of http://schema.org/blogPost
    return entryPoint['http://schema.org/blogPost']['@post']({
      'http://schema.org/name': 'blog post name',
      'http://schema.org/articleBody': 'this is the content of the blog post'
    });
  })
  .then(function (blogPost) {
    // write the IRI of the created blog post to the console
    console.log(blogPost['@id']);
  });

Wat als iemand een client heeft gemaakt met bovenstaande snippet, en ik versioneer aan de server kant een v2 die opeens een extra veld nodig heeft (maw, breaking, vandaar dat ik geversioneerd heb), hoe zou bovenstaande snippet er dan mee omgaan als je zegt dat versionering niet nodig is?

[pietercolpaert]

Die snippet is een sterk vereenvoudigd voorbeeld uiteraard. Bij de eerste promise zal hij alle methoden en velden verkregen hebben, beschreven door de entypoint hier. De invulvelden zullen dynamisch geladen worden en aan de end-user worden gepresenteerd, deze velden kunnen dan gepost worden naar de server. Er is dus zeker geen nieuwe versie nodig om een nieuwe veld toe te voegen.

Andere clients:

• http://comunica.linkeddatafragments.org
• Een voorbeeld uit Smart Flanders: https://codepen.io/pietercolpaert/pen/rdPYXQ

[bertvannuffelen]

Pieter,

je gaat hiervan uit dat de volledige payload tot in elk detail is beschreven.
En dat de transities tussen de versies ook uitgeschreven zijn.

v1

{
   "id": "mijn-identifier"
}

{
   "identificator" : "mijn-identifier"
}

waarbij id mapped op "adms:identifier" en "identificator" op "huppeldup:id".
Zulke overgangen gebeuren in API's. En een generieke client kan enkel beide correct hanteren als ie ook weet dat "adms:identifier" hetzelde is als "huppeldup:id" in de context van deze service (kan verschillend zijn per service).

We moeten dus goed uitschrijven wat de verwachtingen van machine leesbare documentatie is. Hoe ver willen we gaan, en hoe kunnen we dat integreren met OSLO vocabularia enz.

[pietercolpaert]

Goed voorbeeld @bertvannuffelen: was hier inderdaad iets te snel vanuit gegaan. Als er een niet-generieke component nodig is om verdere payload te verstaan, vind ik ergens dat het ook aan de niet-generieke component is om uit te leggen hoe versionering werkt. Want, zelf al weet je dat het niet meer zal werken op een bepaald moment, sowieso moet je een manuele verdere stap zetten om code te veranderen.

Desalnietemin kunnen we hiervoor inderdaad ook een generieke component bouwen uiteraard. Bestaat er al zoiets dat we zouden kunnen aanraden “in het geval dat het nodig zou blijken”?

[bertvannuffelen]

een vraag ivm het nakomingsniveau http.

Stel dat je een bron hebt met een uitgebreide datageschiedenis. Moet dan op elke API memento geimplementeerd worden?

Bij de basisregisters zijn er duidelijk verschillende APIs: detail en Hist. Waarbij Hist een uitbreiding is van detail met datageschiedenis. Het toepassen van memento maakt de Hist overbodig, maar wel heel wat complexer.

Zo zullen we verschillende identificatoren hebben

• https://data.vlaanderen.be/id/adres/123213421 - de PURI die verwijst naar de entiteit zoals die vandaag is.
• https://data.vlaanderen.be/id/adres/123213421/v13 - de PURI die verwijst naar de bovenstaande entiteit op het moment v13.

Hoe dat werkt met memento zullen we nog moeten uitzoeken.