GraphQL - The new "Lingua Franca" for API-Development

  • Published on

  • View

  • Download


The new "Lingua Franca" for API Development "What you want is what you get" About.Me/mhunger Michael Hunger (Director of) Developer Relations Engineering,…


The new "Lingua Franca" for API Development "What you want is what you get" About.Me/mhunger Michael Hunger (Director of) Developer Relations Engineering, Neo4j | @mesirii | I'm no expert in RESTful API design, development and deployment. If in doubt ask the experts, like Stefan, Oliver, Jim, Ian, ... I did a decent share of GraphQL though. You ? Have you heard of GraphQL? Have you used GraphQL? Did you attend the talks from Lars Röwekamp or Manuel Mauky at OOP? Some wise Words on Choosing an API Style • Context matters • API design styles are just tools • Make an informed choice • Choice will affect many aspects (impl, dev-experience, lifecycle) Ways to Build Remote APIs API Design Styles (by Manuel Mauky) Remote API Techniques •RPC (gRPC, CORBA) •WS-* (SOAP) •Publish / Subscribe •Streaming Events (Kafka, Event Store) •REST •GraphQL What? What is GraphQL ? GraphQL is an API query language The "Graph" is the application domain model Specification & Reference Implementation Expressive, extensible nested expressions What is GraphQL not? GraphQL is not a (graph) database query language GraphQL is not a RESTful API GraphQL is not a Silver Bullet Why? Why GraphQL? We were frustrated with the differences between the data we wanted to use in our apps and the server queries they required. GraphQL was our opportunity to rethink mobile app data- fetching from the perspective of product designers and developers. It moved the focus of development to the client apps, where designers and developers spend their time and attention. GraphQL, a data query language. Post by Lee Byron Origins GraphQL - Origins? • Facebook 2012 • efficient queries for mobile clients • minimize latency & roundtrips • "get what you need" • pragmatic development • Open Sourced 2015 • Language Specificiation • Reference Implementation • Quickly Growing Community • esp. in Javascript (React) • but also in backends • Developer Tooling • Working Group for Spec Example Conference - App Conference – App: Listing { onDay(day: Mi) { id title speaker { name } track { name } slot { start, time } }} Conference - Result {[ { id: "98a8ad", title: "Refactoring ..." speaker: [{ name: "Oliver Gierke" }] track: {name: "Modern Architecture"} slot: {start: 9:00, time: 60} }, ... ]} Conference – App: Details { talk(id:"98a8ad") { id, title speaker { name, pic } track { name } slot { start, time, date} abstract, text, audience, level, req }} Conference - Result {[{ id: "98a8ad", title: "Refactoring ..." speaker: [{ name: "Oliver Gierke", pic: "http://..." }] track: {name: "Modern Architecture"} slot: {start: 9:00, time: 60, date: ".."} text: "", level: "Expert", req: "DDD..." } ]} Reuse Retrieved Data { talk(id: "Mi 1.1") { id, title speaker { name, pic } track { name } slot { start, time, date} abstract, text, audience, level, req }} Conference - Schema type Talk { id: ID! title: String! abstract: String speaker: [Person!]! slot: Slot! audience, level, .. } type Person { email: ID! name: String! talks: [Talk] } type Slot { day: Day start: Time } Conference - Schema type TalkMutations { rate(id:ID!, rating:Int, comment:String) : Talk } schema { mutations: TalkMutations } Conference - Mutation mutation rate(id:2342,rating:5, comment:"Really useful") { title speaker { name } } Conference - Result { title: "Cloud Native Java", speakers: [{ name: "Josh Long" }] } GraphiQL Query Tool OOP Demo Takeaway - The Essence of GraphQL: Strict, typed schema enables flexible, safe Queries Goals Goals • Developer productivity • Focus on Front-End needs • Enable Tool Building • Fast Validation • Clear Communication What issues wants GraphQL to solve? • one shape of resource vs. many different needs • custom shape of data query • type safe and valid • latency & roundtrips • updates as commands, http verbs not expressive enough • language for communication between teams • front-end & back-end can develop independently • better developer tooling Design Principles Design Principles •Hierarchical •Product Centric (front-end) • Introspective •Strong Typing •Client‐specified queries Design Principles • a language used to query application servers that have capabilities defined in this specification • does not mandate a particular programming language or storage system • map capabilities to a uniform language, type system, and philosophy • unified interface friendly to product development and a powerful platform for tool‐building Specification What is GraphQL Spec ? • Formal language specification for schema & operations • Developed by Working Group • at Facebook • collaborates with community • Published (regularly) after updates • Reference Implementation (JavaScript) What is in the GraphQL Spec ? • Schema • Types • Query Language • Mutations • Subscriptons • Extensibility • Parameters • Expected behavior • Fragments • Results & Errors • No prescribed transport • Mostly HTTP (GET or POST) Specification Example gi th u b .c o m /s o gk o /g ra p h q l- sc h em a- la n gu ag e- ch ea t- sh ee t Types • Object Types • Unions • Interfaces • Input Typ • Enums • Scalar Types • Built-In: Int, Float, String, Boolean, ID • Nullability • Arrays Query schema { query: QueryType } type QueryType { talksOnDay(day:Day) [Talk] @cached } Mutation schema { mutation: TalkUpdates } type TalkUpdates { rate(talk:Talk, rating:Int) Talk } Mutation input type RatingInput { talk: Talk rating: Int } type TalkUpdates { rate(rating:RatingInput) Talk } Subscriptions type ConferenceSubscription { talkUpdated(track: String!): TalkUpdate } schema { subscription: ConferenceSubscription } Subscriptions subscription { talkUpdated(track: "Moderne Architektur") { id title speaker { name } slot { start, duration } }} Subscriptions •Mutations trigger Domain Events •explicit or implicit •Domain Event triggers Subscription update •Websocket or HTTP transport / PubSub •Supported in Clients Directive type Talk { speaker: [Person] @relation (name:'PRESENTED',direction:OUT) duration: Int @deprecated } Others • (named) Fragments • Union, Interfaces, Enum • Params with defaults • Variables • Aliases • Multiple Operations Execution Executing GraphQL Requests 1. parse (syntax) 2. validate (semantics) 3. execute 1. resolve fields 2. combine results 4. return result or errors new concept Field Resolver + Data Fetcher possibly multiple operations per request SQL NOSQL Static REST GraphQL ServerGraphQL Schema Fi el d R es o lv er + D at aF et ch e r Parse Validate Merge Results computed Transport & Auth GraphQL Transport • Not prescribed • Most often HTTP on /graphql • POST or GET • Hard to cache • HTTP 200 with inline errors • Monitoring / Tracing by middleware GraphQL Auth • In GraphQL server • In Middleware before • In Field resolver •Use of directives @allowed(roles: [Admin]) SQL NOSQL Static REST computed GraphQL Server Mobile Apps SPA (React, Ang, Vue) API Consumers End Users Any Language / Platform Middle ware Cache Aggregator Cache Aggregator Cache Aggregator Development GraphQL Development 1. Schema First – Agree on first iteration of schema 2. Register Schema 3. Implement Type Resolver 4. Fetch Data (static, db, api) 5. Implement Client App view with GraphQL client library 6. Iterate Uses GraphQL Uses Larger Companies • Consolidate sprawling APIs • API domain language • API Facades (Schema stitching) • Wrap data sources & APIs • Automatic API documentation • API monitoring • API evolution Anyone (esp. Startups) • Webapp development • Mobile app development • Quick Prototyping • GraphQL as a service DDD GraphQL and Domain Driven Design Users Introspection Introspection { __type(name:"Talk") { name fields { name description }}} • in every backend • queryable via graphql • for validation • type completion • visualization • fetching Schema SDL Documentation # Conference Sessions type Talk { # id, e.g. Mi 3.2 id: ID! title: String! abstract: String # multiple speakers speaker: [Person!]! } • auto-generated from schema • comments as docs • browseable in client • helpful for type completion GraphiQL Voyager Tools GraphQL DBaaS – Graph.Cool • playground • backed by database • automatic mutation & query generation • automatic field parameters • auth • serverless functions • resolvers • / neo4j-graphql Apollo Launchpad Apollo Engine GraphQL Client Libraries •apollo (js, android, ios) •graphql.js •relay-modern •... GraphQL DB-API / DBaaS • Prisma / GraphCool • Join-Monster • PostGraphQL / PostGraphile • Neo4j-GraphQL Schema Stitching GraphQL Join Apollo Link Gramps (IBM) GraphQL Server Libraries (graphql-*) • JavaScript • Java • Scala (Sangria) • Ruby • Python (Graphene) • Go • .Net • PHP • ... GraphQL Community • GraphQL Summit • 2016,2017,2018 • GraphQL-Europe • 2016, 2017 • GraphQL Slack • 4500 users • Meetups • 65 groups • 23000 members 3 Things I like about Contract for a common vocabulary Flexible Querying Extensibility REST RESTful API • several resources, reachable via URI • links between resources • HTTP as protocol • different representations / media-types, .e.g JSON Philosophy & Guidelines REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. - Roy Fielding Philosophy & Guidelines I think most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. As architectural styles go, REST is very simple. - Roy Fielding New API Description Languages & Tools • Not much tooling in first 5 years • Web Service Description Language (WSDL) • Web Application Description Language (WADL) • Restful Service Description Language (RSDL) • HATEOAS – Hypermedia As The Engine Of Application State • Swagger • RESTful API Modeling Language (RAML) GraphQL – REST Comparison GraphQL REST free operation names for queries & mutations HTTP Verbs strong type safety none operations are fields in schema Resources at URIs model changes require schema + query changes no API change through model change addtive, deprecation, monitoring versioning, tagged resources allows introspection communicates links to operations depending on transport, minimally uses web infrastructure strong tooling some tooling, depending on API tool REST Benefits • Well understood and known • HTTP Protocol incl. Verbs • Web Standards • Web Infrastructure (Caching, Auth) • Isolated Resources • Dynamic links / data in REST API change client behavior REST Issues • Most RESTful API are just HTTP APIs • Effort for complex queries (n+1, latency) • Overfetching, Underfetching • Versioning GraphQL Benefits • Type Safety • Schema = Contract • No overfetching, only resolve requested fields • Single Request • Combining Queries / Reusing existing Results • Good set of libraries • Explicit Specification + Reference Implementation • Active Community / Drivers / Tools GraphQL Issues • Still New / Adoption • Filtering • Aggregation • Auth • Move aggregation to server • Caching in Server & Client • Larger Request Sizes • Can't change hierarchy structure Ressources 1. 2. 3. 4. 5. 6. Artikel MH JS 4/2017 ( demo) Thank YOU Questions? @mesirii