Everyone says it is easy to layer GraphQL on top of REST. Is it really? There are fundamental changes in thought processes which are often neglected, leading to poor schema design. This talk presents a structured approach to thinking in GraphQL and designing user centric schemas. The primary goal of this talk is to present a structured approach to thinking in GraphQL with something I like to call "Activities To Be Done (ATBDs)". I highlight a stepwise process to design a truly "graph-based" schema. We will also see how this approach helps various personas and facilitates in identifying "control points" for a schema.

1. REST to GraphQL
A structured thinking approach
Ankit Muchhala
Technical Lead, Postman

2. “GraphQL can be easily layered
on top of REST APIs”

3. Why is it NOT easy?
Design Principles
• REST is focused on building
loosely coupled apps.
• GraphQL is focused on
product-centric APIs.
Similarity with RPC
• Most tutorials use RPC-like
names for querying.
• Schema scalability suffers.
Thinking in Graphs
• Starting from a REST API may
bias thinking.

4. Example: Let’s build a team!
• Build an API to manage
• Organizations
• Teams
• Users
• Accounts

5. User service
Team service
The REST way
GET /orgs/:org_id
GET /teams/:team_id
GET /orgs/:oid/teams/
GET /teams/:team_id/users
GET /users/:user_id/accounts
GET /organizations/:org_id/users
GET /users/:user_id

6. The Graph-REST way
type Organization {
users: [OrgUser]
teams: [OrgTeam]
}
type Team {
users: [TeamUser]
}
type TeamUser {
team: String
organization: String
accounts: [TeamUserAccount]
}
type OrgUser {
organization: String
}
type User {
id: [...]
accounts: [Account]
}
type TeamUserAccount {
name: String
email: String
}
GET /teams/:id
GET /orgs/:id
GET /orgs/:id/teams
GET /teams/:id/users
GET /orgs/:id/users
GET /users/:id
GET /teams/:id/users/:id/acc..
GET /users/:id/accounts

8. Where did we go wrong?
• We modelled the schema as a
set of disconnected trees.
• It should have been a graph.
• Did not think properly.

9. How to think in graphs?

10. Activities To Be Done (ATBD™)
• Textual description of every action the user
wants to perform in detail.
• Helps you think from a user’s perspective.
• Covers product flows.
• Similar to JTBDs but more fine grained.

11. In our example
• View all teams in an organization.
• View all users in a team.
• Get information about a specific user.
• List all users in an organization.
• Get all accounts registered with an organization.
• List all accounts associated with a user.
• Get information about a team.
• View organization information for a user.
• View team information for a user.

12. Focus on user. Not UI.

13. Noun Analysis
• Highlight the nouns involved in this
description.
• Helps you identify objects, which become
common types.
• Very similar to building an E-R diagram.

14. In our example
• View all teams in an organization.
• View all users in a team.
• Get information about a specific user.
• List all users in an organization.
• Get all accounts registered with an organization.
• List all accounts associated with a user.
• Get information about a team.
• View organization information for a user.
• View team information for a user.

15. Relationship Graphs

16. type Organization {
id: ID
teams: [Team]
}
type Team {
id: ID
users: [User]
}
type User {
id: ID
accounts: [Account]
}
type Account {
id: ID
}

17. How does it matter to me?
• More focus on domain interfaces.
• What language is internal and what is external?
• Forcing function for external API design.
• Promotes user-driven development.
• Allows multiple personas to utilize APIs.

18. Persona Benefits of this approach
Backend Engineer Design and build product-centric APIs
Product Manager Understand domain interfaces
UX / UI Designer Develop a common language in UX and API
Solutions Engineer Faster prototyping of ideas
Engineering Manager Schema is the single source of truth
DevOps Better debugging and optimization
Frontend Engineer Easier to build UI atop user-focused API

19. Thank you
ankit_muchhala