Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

GraphQL 101


Published on

Presentation by Paul Withers and Christian Guedemann on GraphQL and Watson Workspace / Watson Work Services at IBM Connect 2017, San Francisco

Published in: Software
  • Be the first to comment

  • Be the first to like this

GraphQL 101

  1. 1. GraphQL 101
  2. 2. Paul Withers ICS Consultant, Intec Systems Ltd IBM Champion since 2011 OpenNTF Board Member WWS Java SDK developer 2 2/26/2017
  3. 3. Christian Guedemann CTO @ WebGate Consulting AG IBM Champion Chairman of OpenNTF WWS Java SDK Developer, Architect of Watson Workspace Client for IBM Notes / Eclipse 3 2/26/2017
  4. 4. The Problem With REST Multiple calls required • “Joins” are consumer’s responsibility • May result in a large number of REST calls –> Latency is multiplied by the number of calls -> sequential behaviour Provider-driven • Consumer gets what they get, needs to parse accordingly Versions • Changes typically require version increment • May affect consumer’s application object model Validation • Request cannot be validated prior to submission 4 2/26/2017
  5. 5. ENTER GRAPHQL 5 2/26/2017
  6. 6. What Is GraphQL? Created by Facebook 2012 Specification for standard began 2015 Query language • Not database architecture • Not programming language • A modern way to expose your API and give your clients more Control on what they get 6 2/26/2017
  7. 7. Why GraphQL? 7 2/26/2017 Consumer-driven • Returns what the client asks for and no more! Hierarchical • Query and response are both JSON, in same hierarchical structure Strongly Typed • GraphQL type structure ensures query can be tested for syntactical correctness and validity before execution Introspective • GraphQL language can be used to query the type structure
  8. 8. GraphiQL Open source in-browser IDE ( Build validated and syntactically correct queries / mutations and fragments Define query variables Run queries and browse response Run a query to introspect schema Drill down through schema documentation Visualizer tools also available ( 8 2/26/2017
  9. 9. GRAPHiQL 9 2/26/2017
  10. 10. GraphQL and Watson Work Services Documentation online GraphiQL tool for WWS • Must be authenticated in browser to Watson Workspace first! • Queries run as user, not application • Some queries are not available to applications Additional REST endpoints exist (e.g. authentication, focus, photos) • These are usually version-based, e.g. …/v1/… 10 2/26/2017
  11. 11. GraphQL Queries (GET Requests) 11 2/26/2017
  12. 12. GraphQL Query Structure Query can have operation name, optional if only one query Query object has fields for things that can be returned Fields may take (or require) arguments • Arguments have a type (String, Int, ID etc) • See GraphQL documentation for more details • Required arguments have “!” after the type in documentation (e.g. space(id:ID!) • Argument values may be literal or map to variables 12 2/26/2017
  13. 13. GraphQL Query Structure Variables • Passed as an argument of the operation name • Format is “$VariableName: Type” (e.g. $FIRST: Int) • Passed to value of an argument in the operation • Declared as a separate JSON object • Key is variable name as a String • Value is variable value • Validated in GraphiQL IDE, like rest of query 13 2/26/2017
  14. 14. GraphQL Query Structure Fields may have an alias • Format is “alias: field” • Allows query to retrieve multiple result objects of same field type • In response, field type is replaced with alias Fields will themselves have fields and/or objects to return 14 2/26/2017
  15. 15. GraphQL Query Structure Queries on lists may return lots of objects “Slice” using first and last Return pageInfo object to get cursor Pass cursor back to query using before or after 15 2/26/2017
  16. 16. GraphQL Query Structure Fragments can be included to improve readability of complex queries • Defined as separate JSON object • Format is “fragment fragmentName on type” • Allows fields to be defined and validated inline • Used with format “…fragmentName” Schema may return an interface or union type • Inline fragment may be required to act differently depending on actual implementation from interface • Format is “… on type” • Not used in WWS, see GraphQL documentation for examples 16 2/26/2017
  17. 17. Query Fragments 17 2/26/2017
  18. 18. GraphQL Query Structure Directives allow dynamic manipulation of the query based on variables • @include(if: Boolean) • @skip(if: Boolean) 18 2/26/2017
  19. 19. GraphQL MUTATIONS (PUT, POST, PATCH, DELETE Requests) 19 2/26/2017
  20. 20. GraphQL Mutations Mutation can have an operation name Declares the field to set (function) Pass an input object to the field Returns a type • May just be a scalar (e.g. true / false) • May be an object (e.g. a space) • If an object, that can be queried, as in a query Can pass multiple fields (processed sequentially) 20 2/26/2017
  21. 21. GraphQL Subscriptions Subscription allows clients to receive updates Declares the field to subscribe to Pass an input object to the field, including subscription id Nothing yet implemented for this in Watson Work Services 21 2/26/2017
  22. 22. Introspecting GraphQL Schema GraphQL schema can be introspected with GraphQL query! • __schema queries the schema • __type introspects a specific type • kind introspects field type • If NON_NULL, ofType returns its actual type “It’s GraphQL queries all the way down” 22 2/26/2017
  23. 23. GraphQL – Real World Implementation - Facebook - Watson Works Services - Darwino (OpenSource Project hosted on OpenNTF and 23 2/26/2017
  24. 24. Watson Work Services Java SDK Java SDK for Watson Work Service • On OpenCode4Workspace (run by OpenNTF) • Download the project • Consume from Maven <dependency> <groupId>org.opencode4workspace.watson-work-services</groupId> <artifactId>wws-api</artifactId> <version>0.6.0</version> </dependency> • View source code on Stash (includes Junit tests) • Explore implementation in Watson Workspace for Eclipse / Notes Latest documentation on OpenNTF Wiki, Javadoc available 24 2/26/2017
  25. 25. Watson Work Services Java SDK Client authentication as application Client authentication as user Build queries with Java objects, methods and enums No need to construct queries as complex Strings Methods to output built query as String and response as String Conversion of response to Java objects Methods to parse error responses Standard REST endpoints also supported 25 2/26/2017
  26. 26. WWS Java SDK Samples 26 2/26/2017
  27. 27. WWS Java SDK Samples 27 2/26/2017
  28. 28. WWS Java SDK used in OpenNTFs Watson Workspace Client 28 2/26/2017 DEMO
  29. 29. Watson Work Services Java SDK Variables not current supported • Use Java method to construct query based on variable Fragments not currently supported • Use Java method / object to specify standard fields Directives not currently supported • Use Java method to construct query based on variable Aliases not currently supported • Track the JIRA issue 29 2/26/2017
  30. 30. Resources GraphQL website, GraphQL community resources, GraphQL Visualization Tool, WWS developer documentation, WWS GraphiQL IDE, WWS API Java SDK, ces%20Java%20SDK 30 2/26/2017
  31. 31. Notices and disclaimers Copyright © 2017 by International Business Machines Corporation (IBM). No part of this document may be reproduced or transmitted in any form without written permission from IBM. U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM. Information in these presentations (including information relating to products that have not yet been announced by IBM) has been reviewed for accuracy as of the date of initial publication and could include unintentional technical or typographical errors. IBM shall have no responsibility to update this information. THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE USE OF THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT OR LOSS OF OPPORTUNITY. IBM products and services are warranted according to the terms and conditions of the agreements under which they are provided. IBM products are manufactured from new parts or new and used parts. In some cases, a product may not be new and may have been previously installed. Regardless, our warranty terms apply.” Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without notice. Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual performance, cost, savings or other results in other operating environments may vary. References in this document to IBM products, programs, or services does not imply that IBM intends to make such products, programs or services available in all countries in which IBM operates or does business. Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not necessarily reflect the views of IBM. All materials and discussions are provided for informational purposes only, and are neither intended to, nor shall constitute legal or other guidance or advice to any individual participant or their specific situation. It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal counsel as to the identification and interpretation of any relevant laws and regulatory requirements that may affect the customer’s business and any actions the customer may need to take to comply with such laws. IBM does not provide legal advice or represent or warrant that its services or products will ensure that the customer is in compliance with any law 31 2/26/2017
  32. 32. Notices and disclaimers continued Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products in connection with this publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. IBM does not warrant the quality of any third-party products, or the ability of any such third-party products to interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The provision of the information contained herein is not intended to, and does not, grant any right or license under any IBM patents, copyrights, trademarks or other intellectual property right. IBM, the IBM logo,, Aspera®, Bluemix, Blueworks Live, CICS, Clearcase, Cognos®, DOORS®, Emptoris®, Enterprise Document Management System™, FASP®, FileNet®, Global Business Services ®, Global Technology Services ®, IBM ExperienceOne™, IBM SmartCloud®, IBM Social Business®, Information on Demand, ILOG, Maximo®, MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower, PureAnalytics™, PureApplication®, pureCluster™, PureCoverage®, PureData®, PureExperience®, PureFlex®, pureQuery®, pureScale®, PureSystems®, QRadar®, Rational®, Rhapsody®, Smarter Commerce®, SoDA, SPSS, Sterling Commerce®, StoredIQ, Tealeaf®, Tivoli®, Trusteer®, Unica®, urban{code}®, Watson, WebSphere®, Worklight®, X-Force® and System z® Z/OS, are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at: 32 2/26/2017
  33. 33. Thank you 33 2/26/2017 Paul Withers Intec Systems Ltd & OpenNTF @paulswithers Christian Guedemann WebGate Consulting AG & OpenNTF @guedeWebGate