1. Exploring GraphQL / Solution Outline
Avaloq GraphQL
Exploring GraphQL / Solution Outline
Loydl Unternehmensberatung, H. Loydl – 2017

2. Content Explore GraphQL Query Language What is GraphQL, What is it not
REST
GraphQL Type System example
Introspection, Composition, Resolving fields
Mutation, N+1 queries problem solution, Security
Why GraphQL for Avaloq?
POC (slide 25 …)
Other stuff

3. GraphQL Query Language – “Hello World” example{
me {
name }
The “Hello World” of GraphQL
Looks similar to JSON:
Curly Braces → like Objects → selection sets
“name”: Similar to object key → this is a field
fields itself can have selection sets → nested requests → GraphQL is hierarchical following your Object Model (GraphQL: Type Definitions)

4. “name” : “Harald Loydl” }{
me {
name } {
“me” {
“name” : “Harald Loydl” }
With the response on the right side:
A GraphQL query (left side) describes the shape of the resulting data → it’s easy to learn and use
“name” is a property (or field) of “me”
“me” is a top level property → a so called GraphQL server endpoint → capability of the server

5. businessPartner(id: 1) { name } { “name”: “ACME AG” }
Query a specific Business Partner…and get its name
id is a field argument
The field businessPartner is like a function with arguments

6. businessPartner(id: 1) { name address { street city country } {
“name”: “ACME AG”,
“address”: {
“street”: “Förlibuckstrasse”,
“city”: “Zurich”,
“country”: “Switzerland” }
address is a complex object
Here the client requests three fields: street, city, country
No ambiguity
No over- or under-fetching
Predictable Result
This example does not intend to be in accordance with the Avaloq Object Model. Its just an example of a GraphQL query !!

7. businessPartner(id: 1) { name domicile: address(addrType: DOMICILE) {
street
city
country }
postal: address(addrType: POSTAL) { {
“name”: “ACME AG”,
“domicile”: {
“street”: “Förlibuckstrasse”,
“city”: “Zurich”,
“country”: “Switzerland” }
“postal”: {
“street”: “Giessereistrasse”,
specify address type through field argument →here called “addrType” ...in this case the type of the address is defined - type expects a value from an enumeration
Use field alias for address → “domicile”, “postal”

8. businessPartner(id: 1) { name containers { } { “name”: “ACME AG” },
“name”: “container 2” } ]
Query the list of Containers of the BusinessPartner…
SQL would require a join-table here
A REST API would typically expose URLs to follow in a second round trip
GraphQL: “naturally request this in a single query”
Field name applies to every container (gives the name of every container)

9. businessPartner(id: 1) { name containers { positions { } {
“name”: “ACME AG”,
“containers”: [
“name”: “container 1”,
“positions”: [
“name”: “pos 1” },
“name”: “pos 2” } ]
“name”: “container 2”, …
Query all Positions of all Containers of a BusinessPartner…
For Lists I can use field arguments like
orderby: NAME
first: 1 → for pagination through lists

10. What GraphQL is NOT No Database No Storage Engine No Library
No Software to install (i.e. no GraphQL server to buy and install)
Not bound to a programming language
Not bound to a network transport protocol (can use HTTP, websockets, …)

11. What GraphQL IS A Query Language for APIs
A Specification for servers to execute GraphQL queries
A thin API and routing layer (field resolver can fetch data from different sources)
Especially for deeply nested or recursive queries
To fetch exactly the data you need
potentially replaces REST APIs

12. Disadvantages of REST
GET /businessPartner/ /containers
Hard to specify and implement advanced requests with includes, excludes and especially with linked or nested resources
Generic endpoints typically overfetch data
Specific endpoints (per view) are getting pretty ugly to version hell
Over- or under-fetching of data is unavoidable
Too tight coupling between client (views) and server (endpoints)
documentation often outdated
developer uncertain about the responses (ambiguity, trial and error)

13. Avaloq GraphQL Type System
type Query {
me: User
businessPartner (id: Int): BusinessPartner }
type User {
name: String
type BusinessPartner {
Id: Int
address(addrType: AddressTypeEnum): Address
containers(first: Int): [Container]
enum AddressTypeEnum {
DOMICILE,
POSTAL }
type Address {
street: String
city: String
country: String
type Container {
name: String
The Type System allows only correct queries
via the Type System the server expresses its possibilities / capabilities
clients can precisely express their data needs defining queries based on this Type System
→ separation of concerns
→ support a wide range of clients (iOS, Android, Web, ...) with their different needs (because the server actually knows less about the clients)

14. Type System on the Client? …  Introspection{
__schema {
queryType { name }
types {
name
fields {
type {
kind
ofType {name} }
How to get the Type System from the Server to the Client…?
Answer: The Client uses GraphQL itself to query the Type System (Schema) of the Server :-)
uses __schema
→ Introspection → A tool for building tools

15. GraphQL Introspection
→ Validation {
businessPartner (id: ) {
name,
icnatspel }
Advantages:
→ find bugs at development time
→ code generation:
→ custom parsers
→ strongly typed native model objects
→ IDE tooling Integration:
→ context sensitive type ahead
→ real time error detection
Unknown field “icnatspel”
on type “BusinessPartner”
→ IDE Integration
→ Code Generation
→ Auto-Documentation, Deprecation

16. Composition (Fragments){
businessPartner(id: ) {
name
domicile: address(addrType: DOMICILE) {
...addressFragment }
postal: address(addrType: POSTAL) {
fragment addressFragment on Address {
street
city
country
Fragments allows to reuse the same portion of a query on multiple places
A GraphQL fragment is a shared piece of query logic
= UI composition pattern applied to data → UI components reference GraphQL Fragments

17. Resolving fields type BusinessPartner { name: String
address(addrType: AddressTypeEnum): Address
containers(first: Int): [Container] }
Fields like name, address and containers from the Type Definition on the left side are simple functions which actually resolve to a function.
Fields expose a function named ‘resolve’ with parameters (parent-object, field-args, query-ctx) where you implement how you fetch your data
resolve -functions can run concurrently , resolvers per field → lead to N+1 queries problem !! See next slides

18. Mutations
mutation {
createBusinessPartner(name: “Max Muster”, bpType: …) { id name } }
GraphQL allows you to execute mutations
not nested, i.e. “top-level actions” (RootQuery)
have side effects

19. N+1 Queries Problem
Without a caching or batching mechanism, it's easy for a naive GraphQL server to issue new database requests each time a field is resolved.
Solution: Batching and Caching
Further reading:
DataLoader
Query batching in Apollo
Example: fetch a BusinessPartner and all related Persons with their individual names. How to optimize this single request?
A naive approach may issue N round-trips to the backend for the required information.
Solution: a DataLoader will make at most two requests out of this to the backend.
Apollo = favorite GraphQL Client

20. Security
“Oh no, you are letting your users query your database directly…?” (the most awful thing ever)
But… beside possible other solutions (like classic multi-tier)…
We define a Schema
We never expose something we don’t want to expose
We can have max execution time / Timeouts: after x seconds stop the query
We can limit the query depth or query complexity (define field costs)
...
Other solutions could be like the separation of ACP and GraphQL Server, might be also valid
GraphQL could be also used internally between components of the tech stack AND „externally“ for GUIs or other third party components

21. GraphQL – sample of more Features
Subscriptions. Client: “when this/that changes I want updates”. (GraphQL does not make any assumptions on how you implementation it)
Deferred Queries. Client: “show this GUI as fast as possible. But, there is a “deferred” part which can take longer to load. Show this part later when it is loaded”
skip

22. GraphQL - a data abstraction layer
GraphQL is not a storage engine
GraphQL makes almost no assumptions how you access the data → leverage existing code
Existing Application Code
Avaloq
Credit
Risk Mgmt
Compliance
...

23. Why GraphQL for Avaloq? Big picture
numerous clients, multiple platforms, overlapping features
Apps around (micro)services instead of databases
So everything is fine...
Until you call the server….

24. Why GraphQL for Avaloq?
Data fetching performance needs to be massively improved
GraphQL can describe the Avaloq Object Model / arbitrary levels of abstraction
The conceptual problems of REST APIs can be solved ( → Slide 11)
Decoupling the client from the server (decouple features from endpoints)
In applications with deeply nested data structures GraphQL seems to be the natural solution for solving the performance problem - REST in any flavour does not help.
Avaloq DDIC field with parameters = GraphQL fields with arguments
The server describes its capabilities through the Type System. The client sends validated requests and gets exactly that requested data.

25. Demonstrate in the POC…
GraphQL gives developers a much better understanding of Avaloq objects and their relations
Play around with Avaloq data, query and mutate data through an easy to understand query language (showcase GraphiQL)
Significant performance improvements for GUIs incl. mobile
Angular, React, any GUI library can be used to build Frontends, simplicity
Clients get exactly the requested data (predictable, no ambiguity)
Clients get data in one round trip (Performance)
Batching and Caching
Enhancing the API without breaking clients code
Adding new GUI features without changing the server
5.: GraphQL Type Definitions (Schema) is powerful enough (through introspection) to manage deviations from a Standard Avaloq GraphQL Schema (which by itself can be on different Levels of abstraction)

26. Why GraphQL for Avaloq?
GraphQL makes it so much easier to build public APIs aligned to Avaloq internal API i.e. the Avaloq Object Model + no mess with versions or breaking changes
Vastly simplified API release management (no breaking changes anymore, easy support for multiple versions out in the field, easy introduction of new features)
Easy to use and free available GraphQL tools to enhance the developer experience, productivity, more fun to work with
Innovation
In applications with deeply nested data structures GraphQL seems to be the natural solution for solving the performance problem - REST in any flavour does not help.
Avaloq DDIC field with parameters = GraphQL fields with arguments
The server describes its capabilities through the Type System. The client sends validated requests and gets exactly that requested data.

27. POC: Assumptions Business Logic remains in ACP (obviously)
Kernel Layer Business Objects, doc Layer Objects, Avaloq WFC, Rules, etc. ...so everything of relevance in terms of “Avaloq data and transactions” is accessible through internal PL/SQL function/procedure calls
Avaloq can expose this internal PL/SQL API for the needs of this POC and possibly above that for a Node.js production backend implementation
No need to change the internal PL/SQL API at all
Node.js in (or near) the backend is an opportunity for improvements (as discussed here) and does not violate basic architecture or security principles
Avaloq is interested to innovate and to start an incubation project when the outcome of this POC is perceived as an opportunity to improve things

28. POC: Architecture (high level)
Browser, Native App, Frameworks, IDE Tools (e.g. GraphiQL),..
Avaloq Backend
POC to verify the tightest possible integration of the Oracle Database driver for Node.js on the Avaloq PL/SQL backend
Assumptions: we use the existing Avaloq Backend Application Code (PL/SQL API), no need to change that
Propose Oracle DB Node.js driver as integral part of the Avaloq backend
An application caching mechanism based on the specific GraphQL Schema could keep the Frontend running while ACP is shut down / maintenance mode
GraphQL.js server
(Node.js)
Existing Application Code
(internal PL/SQL API)
Oracle DB driver for Node.js

29. POC: Areas of interest Oracle Database Node.js Driver
Connection, Performance and Security
Steps towards a “Node.js in or near the backend” production system
GraphQL
Query and Mutate Avaloq Business Objects
Caching and Batching
Web/mobile GUIs using GraphQL
Schema Customization: from an Avaloq GraphQL “Standard” Schema to a customer specific GraphQL Schema (Banks can adjust to their needs)

30. POC “alternative”: GraphQL Server connects AMI
Browser, Native App, Frameworks, IDE Tools (e.g. GraphiQL),..
Avaloq Backend
POC to verify the integration with AMI
Interesting for Third Party Solution Providers
The GraphQL Server could also be part of the Avaloq Application Server
GraphQL Server
AMI
Messaging Interface

31. node-oracledb (Oracle DB Driver for Node.js)
maintained by Oracle Corp.
powers high performance Oracle DB applications
stable
well documented
open source
doc:

32. GraphQL Server basic components
GraphQL Core
(per language)
lex, parse, validate, execute queries -
based on Type Definitions
Type
Definitions
(Schema)
Avaloq
+ customization
GraphQL
Application
Code
Server for GraphQL endpoint e.g. resolvers, DB connect
For large apps, we suggest splitting the GraphQL server code into 4 components:
Schema
Resolvers
Models,
Connectors

33. Who is using GraphQL

34. Final Notes
Step-by-Step Transition to GraphQL without breaking existing APIs
Start small
The technical integration seems to be very easy
The challenge is to define the right GraphQL Schema

35. The Data Loading Problem
GraphQL:
"the first true comprehensive solution to that data loading problem"

36. Solution Endorsement by Angular and React: Angular 2:
React:

37. Data Fetching No. 1 on Angular Keynote: Apollo GraphQL

38. GraphQL at GitHub

39. Before GraphQL
OK, situations are different at different companies, but you get the point…

40. Now with GraphQL
Sorry for the marketing…

41. Backlog / slides & links
Exploring GraphQL by Lee Byron, Facebook Zero to GraphQL in 30 Minutes – Steven Luscher Implementing and Using GraphQL at GitHub - GitHub Universe From REST to GraphQL (Marc-Andre Giroux) - Full Stack Fest Dan Schafer - GraphQL at Facebook at react-europe Lessons from 4 Years of GraphQL Direct comparison REST / GraphQL in one application (start at minute 28) GraphQL Concepts Visualized

42. GraphiQL in action: http://graphql.org/swapi-graphql/ Star Wars API