Table Of ContentGraphQL and Android
by Mark L. Murphy
GraphQL and Android
by Mark L. Murphy
Copyright © 2016-2017 CommonsWare, LLC. All Rights Reserved.
Printed in the United States of America.
Printing History:
August 2017: Version 0.3
The CommonsWare name and logo, “Busy Coder's Guide”, and related trade dress are trademarks of CommonsWare,
LLC.
All other trademarks referenced in this book are trademarks of their respective firms.
The publisher and author(s) assume no responsibility for errors or omissions or for damages resulting from the use of the
information contained herein.
Table of Contents
Headings formatted in bold-italic have changed since the last version.
• Preface
◦ How the Book Is Structured .................................................................. v
◦ About the Updates ................................................................................ vi
◦ What’s New in Version 0.3? ........................................................ vi
◦ Warescription ..................................................................................... vii
◦ Book Bug Bounty ................................................................................ vii
◦ Source Code and Its License ............................................................. viii
◦ Creative Commons and the Four-to-Free (42F) Guarantee ....... ix
◦ Acknowledgments ................................................................................ ix
• GraphQL in Five Minutes
◦ Step #1: Gotta Get a GraphiQL .............................................................. 1
◦ Step #2: Drafting a Document .............................................................. 2
◦ Step #3: Making the Request ............................................................... 4
◦ Step #4: Looking at the Docs ................................................................ 5
• The Role of GraphQL
◦ So, What Did We Just Do? ................................................................... 9
◦ What Exactly is GraphQL? ................................................................... 11
◦ GraphQL Design Principles ................................................................. 13
◦ Key GraphQL Features ........................................................................ 16
◦ GraphQL Compared To… .................................................................... 18
• Top-Level GraphQL Terms
◦ Document ............................................................................................ 21
◦ Operation ............................................................................................. 21
◦ Operation Name .................................................................................. 22
◦ Arguments and Variables .................................................................... 24
◦ Mutations and Objects ........................................................................ 25
◦ Errors .................................................................................................... 26
• GraphQL Test Environments
◦ The Test Server .................................................................................... 29
◦ GitHub .................................................................................................. 36
◦ And Now, Onwards and Upwards! ..................................................... 37
• Basic Dynamic GraphQL in Android
◦ Dynamic vs. Static ............................................................................... 39
◦ GraphQL and HTTP ........................................................................... 40
◦ Using OkHttp for GraphQL ................................................................ 41
i
◦ Getting a Parsed Response ................................................................. 48
◦ Can’t We Do Better Than Maps of Objects? ...................................... 55
• Basic Static GraphQL in Android
◦ Android Apps and Code Generation .................................................. 57
◦ Introducing Apollo and Apollo-Android ........................................... 59
◦ Using Apollo-Android ............................................................... 60
◦ Names and Apollo-Android ............................................................... 69
◦ Was All of This Worth It? ................................................................... 69
• Objects, Fields, and Types
◦ Introducing the GraphQL Schema Definition Language ................. 73
◦ Objects ................................................................................................. 74
◦ Fields ..................................................................................................... 76
◦ Data Types in GraphQL ....................................................................... 78
◦ Type Modifiers .................................................................................... 88
◦ Trip, In Schema Definition Language ............................................... 89
• Fragments
◦ The Role of Fragments ........................................................................ 93
◦ Creating a Fragment ............................................................................ 95
◦ Using a Fragment ................................................................................. 95
◦ Fragments, And Your Output ............................................................. 97
◦ Fragments and Your Android Code ................................................... 98
◦ Where Apollo-Android Generated Code Gets Generated .............. 100
• Arguments and Variables
◦ Arguments ........................................................................................... 101
◦ Variables ............................................................................................... 111
◦ Variables in Android ........................................................................... 114
◦ A Little Bit of CRUD .......................................................................... 120
• Aliases
◦ Applying Aliases ................................................................................. 133
◦ One, Two, Many, Lots ......................................................................... 135
◦ Aliases with Apollo-Android ............................................................ 139
◦ GraphQL Execution Rules ................................................................. 140
• Interfaces, Unions, and Inline Fragments
◦ Interfaces ............................................................................................ 144
◦ Unions ................................................................................................ 154
◦ Interfaces, Unions, and Apollo-Android .......................................... 156
• Miscellaneous GraphQL Syntax
◦ Arguments on Nested Fields .............................................................. 161
◦ Directives ............................................................................................ 163
◦ Deprecations ...................................................................................... 166
• Introspection
ii
◦ Adding a Type To Your Response ..................................................... 167
◦ Introspection Beyond the Type Name ............................................... 172
• Authentication and the Viewer Pattern
◦ Convention Over Specification ......................................................... 197
◦ What You Get Stems From Who You Are ........................................ 198
◦ Exploring GitHub’s Approach ........................................................... 199
• Queries and Paging
◦ Taking a Page from GitHub .................................................... 209
◦ Examining the Query and Its Results...................................... 213
◦ Please, GitHub, Can I Have Some More? ................................. 214
◦ Paging with Apollo-Android .................................................... 217
• Securing GraphQL
◦ Securing the Network ........................................................................ 227
• Testing GraphQL
◦ Testing Using a Real Server ............................................................... 237
◦ Mocking the Apollo-Android Response ........................................... 238
◦ Mocking the OkHttp Response ....................................................... 240
◦ Mocking the Server Response .......................................................... 240
• Advanced Apollo-Android
◦ Support for Scalar Types .........................................................245
iii
Preface
Thanks!
Thanks for your interest in Android app development, the world’s most popular
operating system! And, thanks for your interest in GraphQL, an increasingly-popular
option for communications between clients and servers.
And, most of all, thanks for your interest in this book! I sincerely hope you find it
useful!
But, however, bear in mind that it will not be funny. Not one little bit. This book will
be completely serious, without any jokes or other forms of humor. Honest.
(well, OK, perhaps not)
How the Book Is Structured
We start off with a quick spin through making GraphQL requests, using canned
tools and custom Android apps. These chapters are designed to help you explore the
basics of exchanging data via GraphQL, plus learn about how GraphQL compares
with other ways that you have used to exchange data (e.g., REST-style Web services).
Next, we take a deep dive into GraphQL syntax. A GraphQL server publishes a
schema, indicating what we can request or modify. In this series of chapters, we will
explore various facets of that schema and learn how we can request or modify that
data given the restrictions imposed by the schema.
Since this book is a work-in-progress, while there will be much more to come, that is
all I can offer you at the present time.
v
PREFACE
Overall, the hope is that this book — when completed – will give you thorough
grounding in how to integrate your app with GraphQL servers.
About the Updates
This book will be updated a few times per year, to reflect new advances in the world
of GraphQL, new approaches for Android integration, and so forth.
If you obtained this book through the Warescription, you will be able to download
updates as they become available, for the duration of your subscription period.
If you obtained this book through other channels… um, well, it’s still a really nice
book!
Each release has notations to show what is new or changed compared with the
immediately preceding release:
• The Table of Contents shows sections with changes in bold-italic font
• Those sections have changebars on the right to denote specific paragraphs
that are new or modified
And, there is the “What’s New” section, just below this paragraph.
What’s New in Version 0.3?
There are two (well, one-and-a-half) new chapters:
• One on paginated GraphQL queries, using the Relay connection pattern,
and how we can consume them in Android
• One partial chapter on advanced Apollo-Android techniques
In addition:
• All URLs in the samples and prose now point to 0.3/ instead of 0.2/ in
their paths
• The samples using Apollo-Android now use 0.4.0 of that library, which in
turn necessitated a small build.gradle change, adding in an apollo closure
and turning off “semantic naming”
• There are a few errata fixes and the like
vi
PREFACE
Warescription
If you purchased the Warescription, read on! If you obtained this book from other
channels, feel free to jump ahead.
The Warescription entitles you, for the duration of your subscription, to digital
editions of this book and its updates, in PDF, EPUB, and Kindle (MOBI/KF8)
formats. You also have access to other titles that CommonsWare publishes during
that subscription period, such as The Busy Coder’s Guide to Android Development.
Each subscriber gets personalized editions of all editions of each title. That way,
your books are never out of date for long, and you can take advantage of new
material as it is made available.
However, you can only download the books while you have an active Warescription.
There is a grace period after your Warescription ends: you can still download the
book until the next book update comes out after your Warescription ends. After
that, you can no longer download the book. Hence, please download your
updates as they come out. You can find out when new releases of this book are
available via:
1. The CommonsBlog
2. The CommonsWare Twitter feed
3. The Warescription newsletter, which you can subscribe to off of your
Warescription page
4. Just check back on the Warescription site every month or two
Subscribers also have access to other benefits, including:
• “Office hours” — online chats to help you get answers to your Android
application development questions. You will find a calendar for these on
your Warescription page.
• A Stack Overflow “bump” service, to get additional attention for a question
that you have posted there that does not have an adequate answer.
• A discussion board for asking arbitrary questions about Android app
development
Book Bug Bounty
Find a problem in the book? Let CommonsWare know!
vii
