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

pwithers@intec.co.uk @paulswithers

https://www.intec.co.uk/blog https://paulswithers.github.io

Christian Guedemann WebGate Consulting AG & OpenNTF Christian.guedemann@webgate.biz

@guedeWebGate https://guedebyte.wordpress.com