Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Starting out with GraphQL

Claire
November 12, 2019

Starting out with GraphQL

REST APIs are now used by just about everyone. The same is not true of GraphQL. Even if you understand the potential they hold, getting started is sometimes too simplistic or assumes too much knowledge. This workshop will provide you with the basics to get started, and tips and tricks to help you solve your own problems away from the workshop.

Claire

November 12, 2019
Tweet

More Decks by Claire

Other Decks in Technology

Transcript

  1. 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
  2. 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
  3. 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
  4. Starting out with GraphQL Sending a Request You can still

    use curl! (jq is very useful for command line JSON)
  5. 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/
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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
  17. 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
  18. 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
  19. 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!
  20. 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!
  21. 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
  22. 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
  23. 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
  24. 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
  25. Starting out with GraphQL Asking for the Schema As before

    you can use curl (fx creates a command line JSON viewer)
  26. 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 ❤
  27. 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!