Gebruiksscenario's voor versioning van velden en directives

Lees eerst de gids Het schema uitbreiden via field versioning, waarin de "field versioning"-functie in Gato GraphQL wordt uitgelegd.

Gato GraphQL staat toe dat velden en directives het argument versionConstraint ontvangen, om te kiezen welke specifieke versie (d.w.z. implementatie) van het veld/de directive je wilt gebruiken:

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

Een veld (of directive) kan ook een standaardimplementatie hebben, namelijk de versie zonder versienummer (en die wordt gebruikt wanneer versionConstraint niet in de query is opgegeven).

Bij introspectie worden alleen gegevens voor de standaardvelden en -directives opgehaald. Als gevolg hiervan zal het argument versionConstraint nooit verschijnen bij introspectie, omdat het standaardveld of de standaard-directive dit niet ondersteunt.

Daarom moeten we altijd van tevoren weten dat een veld of directive twee of meer versies heeft om uit te kiezen, en we moeten weten wat die versienummers zijn. Deze informatie is standaard niet openbaar.

Hoe is versioning dan nuttig? Hier zijn enkele gebruiksscenario's.

​

Een snelle bugfix voor een specifieke gebruiker

Stel dat je een GraphQL API hebt gedeployed op je website, en een specifieke gebruiker klaagt dat het veld niet werkt zoals verwacht. Maar dit geldt alleen voor deze ene gebruiker; niemand anders lijkt problemen te ondervinden.

Je identificeert en verhelpt het probleem, maar je wilt zeker weten dat het werkt voordat je de wijziging voor iedereen uitrolt. Dan kun je de wijziging deployen onder een nieuwe field resolver met versie "1.0.1", en de gebruiker met het probleem vragen om de GraphQL-query aan te passen zodat die naar deze versie van het veld wijst:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Als de bug inderdaad verholpen is, kopieer je de code pas daarna naar de standaard field resolver.

​

Geselecteerde gebruikers vragen een aankomende release te testen

Als een veld of directive een versienummer heeft, en geen standaard (d.w.z. niet-geversioned) implementatie heeft, dan verschijnt het helemaal niet bij introspectie.

{
  someField
    # This directive has no default implementation,
    # so it won't appear during introspection,
    # but it can still be added in the GraphQL query
    # when providing a constraint that satisfies it
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Je kunt het veld of de directive dan deployen en het zal niet zichtbaar zijn in de GraphQL API, en je kunt geselecteerde gebruikers vragen het te testen, waarvoor ze het bijbehorende versionConstraint-argument in hun queries moeten invoeren om het te gebruiken.

Zodra het is geaccepteerd, wordt de versioning verwijderd, en wordt het veld of de directive zichtbaar via introspectie, en daarmee beschikbaar voor iedereen.