GraphQL 101
GraphQL 101
Paul Withers
ICS Consultant, Intec Systems Ltd
IBM Champion since 2011
OpenNTF Board Member
WWS Java SDK developer
2 2/26/2017
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
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
ENTER GRAPHQL
5 2/26/2017
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
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
GraphiQL
Open source in-browser IDE (https://github.com/graphql/graphiql)
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 (http://nathanrandal.com/graphql-visualizer/)
8 2/26/2017
GRAPHiQL
9 2/26/2017
GraphQL and Watson Work Services
Documentation online https://workspace.ibm.com/developer/docs
GraphiQL tool for WWS https://workspace.ibm.com/graphql
• 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
GraphQL Queries (GET Requests)
11 2/26/2017
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
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
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
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
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
Query Fragments
17 2/26/2017
GraphQL Query Structure
Directives allow dynamic manipulation of the query based on variables
• @include(if: Boolean)
• @skip(if: Boolean)
18 2/26/2017
GraphQL MUTATIONS (PUT, POST, PATCH, DELETE Requests)
19 2/26/2017
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
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
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
GraphQL – Real World Implementation
- Facebook - Watson Works Services - Darwino (OpenSource Project hosted on OpenNTF and darwino.org)
23 2/26/2017
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
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
WWS Java SDK Samples
26 2/26/2017
WWS Java SDK Samples
27 2/26/2017
WWS Java SDK used in OpenNTFs Watson Workspace Client
28 2/26/2017
DEMO
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
Resources
GraphQL website, http://graphql.org
GraphQL community resources, http://graphql.org/community/
GraphQL Visualization Tool, http://nathanrandal.com/graphql-visualizer/
WWS developer documentation, https://workspace.ibm.com/developer/docs
WWS GraphiQL IDE, https://workspace.ibm.com/graphql
WWS API Java SDK, https://openntf.org/main.nsf/project.xsp?r=project/Watson%20Work%20Services%20Java%20SDK
30 2/26/2017
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
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, ibm.com, 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: www.ibm.com/legal/copytrade.shtml.
32 2/26/2017
Thank you
33 2/26/2017
Paul Withers Intec Systems Ltd & OpenNTF
[email protected] @paulswithers
https://www.intec.co.uk/blog https://paulswithers.github.io
Christian Guedemann WebGate Consulting AG & OpenNTF [email protected]
@guedeWebGate https://guedebyte.wordpress.com