November 2019 Starting Out With GraphQL Dr Claire Knight 

Dr Claire Knight Senior Software Engineer - GitHub @krider2010 

Starting out with GraphQL Let’s Say Hi! 

Starting out with GraphQL ● Providing context with a very brief background and history ● Getting started with GraphQL ● Welcome to the GitHub Schema ● Lots and lots of exercises to practise applying your knowledge! Workshop Outline 

Starting out with GraphQL Don’t Panic! 

Starting out with GraphQL GraphQL - Background & History 

Starting out with GraphQL What is GraphQL? (1/2) • GraphQL is a query language for APIs • It is (programming) language and storage independent • The API is described by the schema • The schema is based on types (objects) and fields • You access it using a single endpoint - by convention this is /graphql • Continuous evolution is preferred to versions 

Starting out with GraphQL What is GraphQL? (2/2) • It allows you to request what you need and get exactly that returned. No extra data! • It can lead to fewer server round trips because it doesn’t focus on one resource per endpoint • There are three main concepts • Queries - getting data • Mutations - modifying data • Subscriptions - real time updates 

Starting out with GraphQL GraphQL - Getting Started 

Starting out with GraphQL Creating a Request To create a request you write a query… 

Starting out with GraphQL Sending a Request You can still use curl! (jq is very useful for command line JSON) 

Starting out with GraphQL Using Tooling Even though you can use the command line, the interactive nature of GraphQL means that IDE style graphical tools are convenient and helpful. Some examples: • GraphiQL - https://electronjs.org/apps/graphiql • Altair Client - https://altair.sirmuel.design/ • Insomnia - https://insomnia.rest/ 

Starting out with GraphQL GraphiQL Desktop 

Starting out with GraphQL You Try! 

Starting out with GraphQL Understanding the Schema 

Starting out with GraphQL Thinking in Graphs ● Data is modelled as a Graph; types/objects and connections between them ● This is how you then end up with nodes (types) and edges (connections) when writing queries ● Traverse edges to look up related information ● If you visualise a node as a dot/circle, and
 a connection as an edge you end up with
 the graph image which might help you 

Starting out with GraphQL Queries ● This is how data is retrieved from the API ● The root type is usually Query and this includes all other things you can query for ● A successful result of a query will have the same shape as the original query 

Starting out with GraphQL Types ● Nodes! ● Are the same as objects or models in conventional programming languages ● Contain fields - which can be a built in basic type, list, another object type, and more ● Can also contain connections to other nodes 

Starting out with GraphQL Fields and Nullability ● Fields can be scalars (built in primitive types) or other types ● By default all fields can be nullable in GraphQL, but to enforce the presence, use ! ● All queries are ultimately about asking for fields somewhere in the graph of objects 

Starting out with GraphQL Scalars ● These are primitive values ● They don’t need to be defined in the schema ● These are: Int, Float, String, Boolean, or ID ● All fields must resolve down to these ultimately - these are the leaves of the graph 

Starting out with GraphQL Enumerations ● These are field types that are restricted to a set of allowed values ● Often referred to as Enums as that’s how they are defined ● Once defined, they can be used like any other type 

Starting out with GraphQL Arguments ● Every field may accept arguments - depending on their definition in the schema ● These can be required or optional, and there can be more than one ● Default values can be used for optional fields 

Starting out with GraphQL Lists ● As you’d expect it’s a collection of values that a field can hold ● It’s represented, as in many programming languages, with square brackets ● You can combine nullability (or not) with the list itself or it’s elements. Or both 

Starting out with GraphQL Connections ● These allow related objects to be queried without making a separate call (unlike REST) ● Often associated with Relay because of the Relay Cursor Connections Specification ● Realistically this is just cursor based pagination 

Starting out with GraphQL Pagination ● Sensible limits on connections ● The connection must have edges and pageInfo ● Edges must have node and cursor fields ● Arguments of first and after are used to handle the pagination with cursors 

Starting out with GraphQL Aliases ● These let you rename the result of a field to anything else ● You need this if two fields would conflict in the response ● This can happen when you query based on arguments 

Starting out with GraphQL Interfaces ● As with many programming languages, these are like abstract types ● It has a list of named fields that are are shared (or need to be provided for) all implementing types 

Starting out with GraphQL Unions ● Unions are similar to interfaces but don’t specify any common fields ● A union represents many possible types ● Using a union provides flexibility and allows a form of polymorphism 

Starting out with GraphQL Inline Fragments ● These are used with Interfaces and Unions to access the data based on type ● The … indicates it is a fragment ● For inline fragments you must also specify the type to match on ● You can match on Interfaces as well! 

Starting out with GraphQL Named Fragments ● These are very similar to inline ones, but because they are named they can be reused ● Their main use is to split complicated queries into smaller chunks to make it easier to understand ● And avoid repetition! 

Starting out with GraphQL Mutations ● This is how data is written via the API (create or update) ● The root type is usually Mutation and then includes all the things you can mutate ● You need to pass in data to a mutation using Input Objects and often Variables 

Starting out with GraphQL Input Objects ● This is how complex objects are passed, which is most necessary when writing Mutations ● Fields in an input object can reference other Input Objects ● However they cannot have arguments or reference output types 

Starting out with GraphQL Variables ● These are always written as $variableName ● Definitions specify the type - $lockReason: LockReason ● Types must be Scalars, Enums, or Input Objects ● Default values van be provided ● Variables can also be used inside fragments 

Starting out with GraphQL Directives ● These describe additional options, and are most powerful server side ● Written as @name, e.g. @deprecated ● They can be used in the Schema and in Queries ● Only two are defined by in the spec: @skip and @include 

Starting out with GraphQL GraphQL - GitHub Schema 

Starting out with GraphQL Download from: https://developer.github.com/v4/public_schema/ schema.public.graphql 

Starting out with GraphQL Or… 

Starting out with GraphQL Query for it! 

Starting out with GraphQL Asking for the Schema As before you can use curl (fx creates a command line JSON viewer) 

Starting out with GraphQL You Can Also Use GraphQL! 

Starting out with GraphQL Be Warned - It’s Large! 

Starting out with GraphQL Exercises 

Starting out with GraphQL Guidance Experiment. Don’t be afraid to try things out! Work at your own pace. Answers will be available after the workshop Don’t worry about asking for help or advice. We are here to help you ❤ 

Starting out with GraphQL Questions to Answer (using ) 1. How long have you had your GitHub account? 2. Which repositories have you starred? 3. Which was your first (created) repository on GitHub? 4. Does anyone follow you and do you follow anyone on GitHub? 5. Which items have you pinned? 6. What repositories do you have? For each one is it a fork? 7. Who else has contributed to those repositories? 8. Which organisations do you belong to? 9. Do you have any pull requests you need to review? 10. Are you assigned any issues at the moment? • Use a mutation to create a new repository • Now add an issue to that repository • Then add a reaction to that issue! • Finally, also add a comment Mutate Things! 

Starting out with GraphQL Answers and Useful Links: https://bit.ly/graphql-resources https://speakerdeck.com/krider2010 

No content