8 Designing GraphQL APIs

GraphQL is one of the most popular protocols for building web APIs. It’s a suitable choice for driving integrations between microservices and for building integrations with frontend applications. GraphQL gives API consumers full control over the data they want to fetch from the server and how they want to fetch it.

In this chapter, you’ll learn to design a GraphQL API. You’ll do it by working on a practical example: you’ll design a GraphQL API for the products service of the CoffeeMesh platform. The products service owns data about CoffeeMesh’s products as well as their ingredients. Each product and ingredient contains a rich list of properties that describe their features. However, when a client requests a list of products, they are most likely interested in fetching only a few details about each product. Also, clients may be interested in being able to traverse the relationships between products, ingredients, and other objects owned by the products service. For these reasons, GraphQL is an excellent choice for building the products API.

8.1 Introducing GraphQL

8.2 Introducing the products API

8.3 Introducing GraphQL’s type system

8.3.1 Creating property definitions with scalars

8.3.2 Modeling resources with object types

8.3.3 Creating custom scalars

8.4 Representing collections of items with lists

8.5 Think graphs: Building meaningful connections between object types

8.5.1 Connecting types through edge properties

8.5.2 Creating connections with through types

8.6 Combining different types through unions and interfaces

8.7 Constraining property values with enumerations

8.8 Defining queries to serve data from the API

8.9 Altering the state of the server with mutations