GraphQL je specifikace dotazovacího jazyka. GraphQL samotné neumí operace s daty ani jejich transformování, jde o jazyk, kterým se dotazujeme služeb implementujících jeho specifikaci. GraphQL je zaměřeno na tvorbu klientských aplikací, tak aby vývojáři mohli začít využívat data bez nutnosti strávit spoustu času studiem dokumentace API.

Specifikace GraphQL je dostupná tady: http://spec.graphql.org/ 

Hlavní principy GraphQL

• Zaměřený na produkt (Product-centric) – GraphQL se řídí tím co potřebuje front-end zobrazující data.
• Hierarchický – GraphQL podporuje vnořená data. Díky nim lze v rámci jednoho dotazu získat i všechna související data bez nutnosti více dotazů. Dotazy v GraphQL mají navíc stejný formát jako odpověď na ně.
• Silné typování – Každá aplikace v GraphQL má definovaný svůj typový systém.
• Klient-specifické odpovědi – Každý klient je zodpovědný za specifikaci toho jak bude konzumovat data. O co si řekne to dostane a přesně v takovém formátu v jakém si o to řekl.
• Introspekce – GraphQL umožňuje introspekci a tak se lze GraphQL serveru zeptat jaké přesně datové typy podporuje, jak vypadají atd. Čehož zároveň využívají nástroje pro vývoj s GraphQL pro typovou kontrolu, našeptávání atd.

Benefity

• Umožňuje klientovy přesně nadefinovat jaká data chce v odpovědi (fields v queries), jak se mají jmenovat (aliases), jakou mají mít strukturu, tak aby je klient mohl rovnou použít a zobrazit bez nutnosti post-processingu.
• Jednotlivé pole mohou mít své argumenty (to umožňuje například specifikovat v jaké měně chceme vrátit cenu zboží).
• Přesouvá velkou část práce na sever – výpočty, formátování odpovědi, atd. takže klient může být jednoduché zařízení/aplikace, které data pouze zobrazí.
• GraphQL server může mít jako backend různé zdroje dat (REST APIs, databáze, služby, atd.) a data z těch všech prezentovat jednotně, klidně v rámci jediné odpovědi na jeden dotaz bez nutnosti klienta řešit jak přistupovat k těmto různým zdrojům.
• Díky svému designu předchází “over/under fetchingu”. Tj. Situacím kdy klient dostane více dat než potřebuje (a zbytečně zneužívá kapacitu připojení) či méně dat než potřebuje (a pak musí dělat dodatečné dotazy a tak má větší latenci).
• GraphQL typicky pracuje přes HTTP, takže funguje prakticky všude a není potřeba speciální konfigurace sítě, firewallu, atd.
• GraphQL API lze snadno mockovat a tak frontend vývojáři mohou začít pracovat už v době kdy backend ještě neexistuje.

Základní komponenty

• Schema – Je definováno serverem (na serveru) na základě toho jaká data potřebují klientské aplikace. Schéma definuje datové typy.
• Resolver – Funkce na serveru zodpovědná za získání dat datových typů definovaných ve schématu.
• Query – Dotaz pro získání dat
• Mutation – Mechanismus pro změnu dat (přidání, úpravu, smazání) na serveru.
• Fragment – Znovupoužitelný blok kódu definující seznam polí, který lze sdílet mezi více dotazy (queries) a tím pádem zkrátit zápis dotazů a usnadnit správu. Fragment je vždy definován pro konkrétní datový typ.
• Subscription – Mechanismus pro naslouchání změně dat v reálném čase. Funguje přes WebSockets. Úplně první použití bylo ve facebooku pro živé aktualizace lajků na statusech.
• Proměnné (query variables) – Mechanismus umožňující parametrizaci dotazů.

Schema definition language

• Skalární typy:
  • Int
  • Float
  • String
  • Boolean
  • ID
• Vykřičník za datovým typem znamená, že je to povinný atribut (non-nullable).
• List – []
  • labels: [Label] – list může být null a může obsahovat null
  • labels: [Label]! – list nemůže být null, ale může obsahovat null
  • labels: [Label!]! – list nemůže být null a nemůže obsahovat null

Poznámky

• GraphQL nemá nic jako je hvězdička “*” v SQL, která vrátí všechny sloupce. V GraphQL musí klient přesně říct jaká pole chce dostat.
• Při vkládání nové položku co má hodně atributů je možné je zapsat jako json object při použití “input”
  • mutation {
  vlozeniNovehoPrvku(input:{
    JSON HERE
  }) {
      co chci zobrazit
  }
}
• Některé stacky pro GraphQL:
  • https://www.apollographql.com/
  • https://hasura.io/
  • https://www.prisma.io/
  • https://aws.amazon.com/appsync/

Ukázková aplikace

Ukázkový GraphQL server napsaný v Pythonu využívající Flask jako webserver, Ariadne jako GraphQL server a SQLAlchemy databázový toolkit pro přístup k ukázkovým datům uložených v sqlite databázi. Tuto ukázkovou appku jsem si sepsal když jsem se učil principy GraphQL a chtěl jsem si je vyzkoušet v praxi:

https://github.com/Tojaj/sample-graphql-flask-sqlalchemy-app