4 Designing a GraphQL schema

 

This chapter covers

  • Planning UI features and mapping them to API operations
  • Coming up with schema language text based on planned operations
  • Mapping API features to sources of data

In this chapter, we are going to build a real data API for a real web application. I picked the name AZdev for it, which is short for “A to Z” of developer resources. AZdev will be a searchable library of practical micro-documentation, errors and solutions, and general tips for software developers.

I am not a fan of useless abstract examples that are removed from practical realities. Let’s build something real (and useful).

4.1 Why AZdev?

When software developers are performing their day-to-day tasks, they often need to look up one particular thing, such as how to compute the sum of an array of numbers in JavaScript. They are not really interested in scanning pages of documentation to find the simple code example they need. This is why at AZdev, they will find an entry on “Calculate the sum of numbers in a JavaScript array” featuring multiple approaches on just that particular code-development need.

AZdev is not a question-answer site. It is a library of what developers usually look up. It’s a quick way for them to find concise approaches to handle exactly what they need at the moment.

Here are some examples of entries I would imagine finding on AZdev:

4.2 The API requirements for AZdev

4.2.1 The core types

4.3 Queries

4.3.1 Listing the latest Task records

4.3.2 Search and the union/interface types

4.3.3 Using an interface type

4.3.4 The page for one Task record

4.3.5 Entity relationships

4.3.6 The ENUM type

4.3.7 List of scalar values

4.3.8 The page for a user’s Task records

4.3.9 Authentication and authorization

4.4 Mutations

4.4.1 Mutation input

4.4.2 Deleting a user record

4.4.3 Creating a Task object

4.4.4 Creating and voting on Approach entries

4.5 Subscriptions