Oversigt over skemaet

 

Introduction

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

Vi har to offentligt tilgængelige skemaer: public og experimental.

I vores public skema finder vores stabile API. Dette skema vil aldrig opleve bagudkompatible ændringer uden for vores større publiceringer. Vi leverer en tidslinje inden enhver kommende major release, og alt, der står til at blive fjernet, vil altid være markeret som "Deprecated".

I vores experimental skema finder vores bleeding-edge API, som nøje afspejler det, vi bruger internt til at køre den nye administration. Dette API, vigtigt, BØR IKKE betragtes som stabilt, og kan ofte gennemgå breaking changes. Som sådan rådes du til at bruge dette skema efter eget skøn.

Vi tager gerne imod feedback til begge skemaer. Det vil dog være experimental skemaet hvor der er størst mulighed for at få ændringer inkluderet.

Vi opfordrer derfor udviklere til at holde øje med vores experimental skema for, da det fungerer som preview til potentielle kommende ændringer af vores public API, som altid vil være tilgængelig i experimental skemaet først. Dette giver dig ikke kun indsigt i den mulige fremtidige tilstand for public skemaet, men giver dig også mulighed for at give værdifuld tidlig feedback.

 

Vær opmærksom på:

På grund af begrænsningerne i den API-gateway, som vi benytter i øjeblikket, understøttes nogle funktioner i den officielle GraphQL-specifikation ikke.

Dette inkluderer især (men er ikke nødvendigvis begrænset til):

• Auto-wrapping af enkeltelementer, som suppleres hvor der forventes en liste, f.eks. ved supplering af "foo" når [String] forventes.

Vi har en løsning på vej, så dette bliver rettet på sigt.

 

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:

 

Generel struktur

I øjeblikket tager vores forespørgsler og mutationer flere forskellige former, men det "offentlige" skema afspejler, hvordan vi agter at skemaet skal se ud på sigt. Dette afsnit skitserer denne struktur.

Alle forespørgsler og mutationer tager denne form:

    mutation entityAction(input: EntityActionInput): EntityActionPayload!
    

    query someQuery(input: SomeQueryInput): SomeQueryPayload!
    query otherQuery(): OtherQueryPayload!
    

Dette giver en ensartet struktur for alle GraphQL-forespørgsler og svar. Returtypen for en forespørgsel/mutation som f.eks. "PageCreatePayload", indeholder resultatet af anmodningen samt eventuelle fejl, der opstod som et resultat af ugyldige brugerinput.

Som fortsættelse af foregående eksempel er dette strukturen for returtypen "PageCreatePayload":

    type PageCreatePayload {
        content: Page
        errors: [PageTreeClientError!]!
    }
    

 

 

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.