 Resources from Nik Graf in 2021

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

graphql

While it's certainly possible to version a GraphQL Schema, it's common practice to not do so.

That's fine when just adding new queries or fields, but now and then we want to change a type or remove a field. Leveraging multiple deploys and deprecations we can make breaking changes in a GraphQL schema without affecting a single user.

In this lesson we use one field renaming example to walk through such a multi-step process.

Evolving a GraphQL Schema incl. Breaking Changes without affecting a Single User

Naming variations can easily be solved by postfixing the name with the variation. This though can quickly lead to a bloated schema, which we want to avoid.

On the contrary by using arguments our schema becomes less flexible.

In such cases GraphQL Aliases become a vital element to enable developers to do the same things as with multiple fields, but without any of the downsides. 

Naming Conventions for Fields with GraphQL Aliases in Mind

A Connection can be extended in multiple ways:

- Fields representing meta information on a entity relationship can be added
- PageInfo itself can be enhanced
- Arguments for filtering or ordering can be applied

In this lesson we walk through all of them to demonstrate the flexibility of the Connection Specification.

Extending GraphQL Connections with additional Fields and Arguments

When naming queries there are almost now rules or recommendations. Nevertheless it's recommended to at least have some conventions in order to reduce cognitive overhead for developers.

In this lesson we explore some the the common best practices.

Naming top-level Query Fields in GraphQL

Relay comes with a specification and a set of well define conventions for GraphQL Mutations. By following the conventions, we not only design Mutations in a way that they can be extended with easy, but also reduce a lot of cognitive overhead.

We can summarise the conventions into 5 rules:

1. Mutations are named as verbs `createProduct`, `introduceShip`, `deleteCollection`.
2. There must be a single argument input
3. The input type name is the capitalised mutation name with a `Input` postfix e.g. `CreateProductInput`, `IntroduceShipInput`.
4. The returned value is a new custom type that can contain various fields.
5. The return type is name is the capitalized mutation name with a `Payload` postfix e.g. `CreateProductPayload`, `IntroduceShipPayload`.


Mutation Input and Payload Structure in GraphQL

Being able to resolve related entities in one query is one of the most beneficial features of GraphQL.

While the simples solution often is the best, this doesn't hold up for GraphQL connections. The ideal solution is based on the [Relay Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm).

In this lesson we start based on a simple solution and apply one feature request after another. Eventually we end up with the Connection Specification. 

Paginate Entries using the Connection Specification

In theory it's quite easy to dynamically generate queries at runtime based on a parameter, but not a lot of GraphQL clients handle it well. It's not so much about the clients, but all the tooling around it like generators, editor integrations and the opportunity to leverage persistent queries.

Using plural instead of singular arguments will allow your clients to use static queries for situations where they usually would need dynamic ones.

Optimising GraphQL Mutations for Static Usage

In this lesson we design the mutations for a webshop checkout flow in two variations. First based on the data model, then based on the domain model.

Once we have both available we can compare them and explore the pros and cons.

Design GraphQL Mutations by focusing on the Domain rather than the Data Model 

Feedback & Questions are very welcome at [https://twitter.com/nikgraf](https://twitter.com/nikgraf)

Thanks to everyone involved helping me to create this course, but especially to:
- Mikhail Novikov [https://twitter.com/freiksenet](https://twitter.com/freiksenet)
- Sean Grove [https://twitter.com/sgrove](https://twitter.com/sgrove)
- Marc-André Giroux [https://twitter.com/__xuorig__](https://twitter.com/__xuorig__)

Course Outro for Designing GraphQL Schemas

In this short clip Nik shares why is story how this course came to be.

Course Intro for Designing GraphQL Schemas 

A common requirement for connections is to add and remove items. We could go with two separate mutations: add & remove versus a single update mutation. In almost all situations it's better to have two separate mutations and in this lesson we explore why.

GraphQL Mutations to update Connections

While being specific is great when designing GraphQL Mutations, in some cases this can lead to a large number of Mutations. Especially when the use-case is to update one entity, it raises the question if can or should do just one update mutation.

It's certainly possible, but requires some tradeoffs. Most commonly we have to make non-nullable fields nullable. In this lesson we use an `updateProduct` example to elaborate why this tradeoff is needed.

Topics

Instructors

Content Type

Free or Pro