Oversigt over skemaet

I denne artikel:


Attention   

 

Introduktion

For at styrke din forståelse af GraphQL API er her nogle punkter, som du bør gøre dig nærmere bekendt med.

 

Versionering

GraphQL API benytter semantisk versionering som sit versioneringsparadigme.

Semantisk versionering foreskriver versionsnumre i formen <major>.<minor>.<patch>, som f.eks. 1.12.34. Hvis bagud inkompatible ændringer introduceres, SKAL major versionsnummeret forøges. Så hvis vi omdøber eller fjerner et felt fra en type, forespørgsel eller mutation, udløses et major versionsnummer skift. Dette er dog noget, som vi vil forsøge at begrænse for at forlænge API'ets levetid, samt for at give en bedre oplevelse for API-klienter. Udfasning eller tilføjelse af felter, udløser et minor versionsnummer skift. Hvis vi ændrer beskrivelsen, eller sorteringen af felter eller typer, eller hvis bagudkompatible rettelser (bugfixes) udføres, forøger vi patch versionsnummeret.

 

NOTE VED BETA:

Imens API'et er i betaversion (dermed menes, at vi aktivt er i gang med at udvikle API'et), vil vi benytte major versionsnummer 0. Dette betyder at vi i betafasen, vil opskrive minor versionsnummeret (og ikke major versionsnummeret), hvis der publiceres en baglæns inkompatibel ændring.

 

Generelle principper

Der er en række konventioner, som vi benytter gennemgående i API'et:

  • Typer navngives altid med upper camel case, f.eks. OrderLine.
  • Forespørgsler (queries) og mutationer (mutations) navngives altid med camel case, f.eks. orders.
  • Mutationer navngives altid således at entiteten, som mutationen påvirker, listes først, efterfulgt af typen, af den hændelse der udføres. F.eks orderCreate.
  • Konstanter (gyldige poster i en enumeration) benyttes oftest navne med CAPS og underscores, f.eks. GREATER_THAN, an instance of SearchComparator.
    • Bemærk: Den eneste undtagelse for dette er typer, som enumererer felter på en anden type. Et eksempel kunne være elementer i OrderSearchInputField enumerationen.