Principled GraphQL
Principled GraphQL
GraphQL, despite the name, isn't simply a query language. It's a comprehensive solution to the problem of connecting modern apps to services in the cloud. As such, it forms the basis for a new and important layer in the modern application development stack: the graph. This new layer brings all of a company's app data and services together in one place, with one consistent, secure, and easy-to-use interface, so that anyone can draw upon it with minimal friction.
At Apollo, we've been building industry leading graph technology since 2015, and we estimate our software is now used in over 90% of GraphQL implementations. Over the years, we've had thousands of conversations with developers implementing GraphQL at companies of all sizes. We want to share what we've learned, so we've distilled their experiences into a set of best practices for creating, maintaining, and operating a graph. We present them here as 10 GraphQL Principles, broken out into three categories, in a format inspired by the Twelve Factor App.
Integrity PrinciplesEnsuring that the graph is well-defined, stable, and consistent
1. One Graph
Your company should have one unified graph, instead of multiple graphs created by each team.
2. Federated Implementation
Though there is only one graph, the implementation of that graph should be federated across multiple teams.
3. Track the Schema in a Registry
There should be a single source of truth for registering and tracking the graph.
Agility PrinciplesRapidly rolling out the graph and continuously adapting it to changing needs
4. Abstract, Demand-Oriented Schema
The schema should act as an abstraction layer that provides flexibility to consumers while hiding service implementation details.
5. Use an Agile Approach to Schema Development
The schema should be built incrementally based on actual requirements and evolve smoothly over time.
6. Iteratively Improve Performance
Performance management should be a continuous, data-driven process, adapting smoothly to changing query loads and service implementations.
7. Use Graph Metadata to Empower Developers
Developers should be equipped with rich awareness of the graph throughout the entire development process.
Operations PrinciplesSecurely deploying the graph to production at scale
8. Access and Demand Control
Grant access to the graph on a per-client basis, and manage what and how clients can access it.
9. Structured Logging
Capture structured logs of all graph operations and leverage them as the primary tool for understanding graph usage.
10. Separate the GraphQL Layer from the Service Layer
Adopt a layered architecture with graph functionality broken into a separate tier rather than baked into every service.