chollier / schema-extensions

An example repository to store and edit GraphQL schema extensions with graphql-faker

GraphQL Extensions

This project contains a repository of suggested or draft extensions or changes (as minimal as possible for the latter) to your GraphQL Schema. Using GraphQL Faker you will be able to proxy your existing schema but also to mock and simulate the proposed changes

Table of Contents

• Set up Instructions
• GraphQL First development process
  • I'm an engineer scoping or designing a new feature
  • I'm a back-end engineer and I worked on some of the proposed changes, they just made it to master.
  • I'm a front-end engineer and I want to use one of the extensions here

Set up Instructions

1. Setting up the project:

First, run npm to initialize the project dependencies

npm install

2. If you schema endpoint requires authentication, insert here instructions to fill in the Header with an auth token or another kind of authentication. Example:

Log in to http://mycompany.com, then run this in the javascript console (Shift-Cmd-J):

JSON.parse(localStorage.getItem("session")).accessToken

This will return a string that you need to copy and paste in the next command

3. Running an extension file:

npm start -- --open --extend [your GraphQL endpoint] --header "Authorization:Bearer [THE AUTH TOKEN YOU GOT]" ./example.faker.graphql

GraphQL First development process

We have found that using GraphQL First brings us efficiency and gains in productivity. Here are a few guidelines to make this happen:

I'm an engineer scoping or designing a new feature

Since the schema will be used by the front-end team and implemented by the back-end team, it's recommended to pair with a peer when possible. Brainstorming a new schema extension in graphql-faker is very easy:

1. first create a new file in this repo, e.g.: user-avatar.faker.graphql
2. follow the Set up Instructions to start the project with this file:

yarn start --open --extend http://localhost:3000/graphql/queries --header "authorization:Bearer [THE AUTH TOKEN YOU GOT]" ./user-avatar.faker.graphql

3. Write your extensions:
4. Visualize your changes in GraphiQL

5. Try you Query:

6. Open a pull-request and ask for review.
7. Get feedback, when there's a consensus, merge your PR.

I'm a back-end engineer and I worked on some of the proposed changes, they just made it to master.

Great! Thanks for that 🍾.

If you only incrementally added some types from an extension suggestion, there's one last thing you should do. Since graphql-faker can only extend and not override types, you need to remove from this file the types you just implemented, otherwise it will complain that the type already exists. Finally let the people who will use API or notify the #graphql channel of the recent release.

I'm a front-end engineer and I want to use one of the extensions here

Great news, you can start before the back-end is even implemented. You are only a few steps before productivity:

1. clone this repository
2. follow the Set up Instructions to start the project with the extension you wish to use:

yarn start --open --extend http://localhost:3000/graphql/queries --header "authorization:Bearer [THE AUTH TOKEN YOU GOT]" ./user-avatar.faker.graphql

3. explore the schema and get familiar with the extensions
4. eventually you might want to improve some of them to bring realistic mocks or hardcode examples:

type Avatar {
  # The original avatar URL
- originalUrl: String
+ originalUrl: String @fake(type:avatarUrl, options: { imageCategory: people })
  # The thumbnail resized to 64x64px
- thumbnail64Url: String
+ thumbnail64Url: String @examples(values: ["http://example.com/image.jpg", "http://example.com/image2.jpg"])
}

5. open a pull-request with these improvments, they might be useful to others!