Adopting Federated GraphQL at State Farm — Our First Baby Steps
By Austin Mehmet and Brian Vanderbusch
Overview
State Farm’s digital strategy has evolved over the years, from the early days when we had a simple static home page, to today where we have numerous APIs and multiple separate frontends stitched together to provide a cohesive customer experience. A core part of our web architecture relies on numerous Backend for Frontends (BFFs) that provide central orchestration of REST APIs to ensure our customers get a unified experience across our digital landscape. These API orchestration layers have served us well, but ongoing maintenance has become more cumbersome over the years as the downstream APIs upgrade and evolve over time. Some of our larger orchestration APIs may have been generic enough for multiple various clients to consume, but they never grew to become enterprise-wide solutions. While this architecture is functional, it is far from optimal. Recognizing the need for a more efficient solution, we turned our attention to GraphQL and a federated architecture.
The Shift to Federated GraphQL
GraphQL was not new to State Farm. It had been developed in isolated pockets within the organization but had never achieved widespread adoption. However, the adoption of federated GraphQL changed our perspective entirely. Why? Because it allows us to unify our numerous web services under a new concept: the supergraph. The supergraph acts as a single point of entry across our wide sprawl of APIs and enables clients to request only the data they need while also not having to navigate a maze of various web service that span paradigms like REST, SOAP, GraphQL, and gRPC. It opens the door to no longer having to maintain massive monolithic backend-for-frontend style APIs, but instead have our downstream domain areas power the client facing applications theoretically removing large chunks from our architecture that could potentially improve performance and reduce cost. We also saw other various benefits such as enabling security at a field level, increasing developer productivity, and greater flexibility to adapting to new business features. But maybe one of the most important aspects was that we saw a large benefit in building and maintaining a single unified schema for describing common business terminology to our clients. It isn’t uncommon for areas to call the same concepts different things. Simple things like addressLine1 being called street1 or just line1 or concepts like a vehicle were being represented as vehicle, car or, in some systems, generically as an insurableRisk. Apollo GraphQL’s approach to GraphQL federation lets us wrangle some of that in and have a more unified schema for modeling our business processes and enables a common language in which we can all talk in.
The Proof of Concept
We decided to validate this approach with a proof of concept. Collaborating closely with Apollo and leveraging their product GraphOS, we set out to build a thin slice of what we believed would showcase the full potential of federated GraphQL at State Farm. Our concept focused on modeling a policy retrieval system. This system allowed us to fetch policy details, agent details, claims details, and customer details all through a single supergraph. We ended up building 10 subgraphs that exposed 15 queries, 1 mutation, 63 types and 378 fields. Pages that would require multiple network requests to gather up the data they needed to paint a screen could now all be done with one call against our supergraph. Most of the subgraphs built were facade layers that sat on top of existing REST APIs. This was the simplest and quickest way forward to demonstrating the value of the supergraph to our organization. Much of the complexity we had to wade through was reorganizing existing schema into cleaner consumable parts and enabling the federation of our entities. In terms of languages and frameworks, we mainly stuck to Typescript using Apollo Server but also enjoyed branching off that path and trying Java with DGS and Go with gqlgen. Many of our internal services are already written in Java with Spring and so DGS has offered a more unique approach of simply embedding a GraphQL interface into existing APIs rather than spinning up new services.
Challenges We Faced
Like any transformative project, our journey with federated GraphQL was not without its challenges:
- Complexity of Integration: Integrating numerous existing services into a unified supergraph required significant effort. Each service had its own intricacies and dependencies that needed to be carefully managed. In the context of our concept, some constraints of our legacy systems introduced unexpected complexities in tasks like policy retrieval across our various domains.
- Schema Management: Coordinating schema across various teams and services presented some challenges. Initially, we identified opportunities to improve the consumer-friendliness of our existing REST and SOAP schemas as most were never really intended to be exposed to a UI. We spent a lot of effort working back with these various areas to rethink that schema. We also needed tooling and processes to handle schema evolution and versioning. Apollo’s GraphOS helped solve that problem with their schema proposal changes feature which allowed us to have complete conversations on supergraph schema. We also encountered some difficulties with composition and collaboration within a shared type pool. Specifically, aligning on consistent naming conventions for types used by different teams was an area that required extra coordination.
- Security: Ensuring the security of our federated graph was paramount. We are still exploring ways to implement stringent access controls and data validation mechanisms to protect sensitive information through the implementation of the @policydirectives via a coprocessor.
- Scale: When faced with a large task, such as creating a sustainable supergraph for a large organization, it is important to take extra time to plan and keep the long term goal in mind from the beginning. We knew that our proof of concept would need to be focused on 10 teams spread across our IT operations workforce, and they would become the catalyst for expansion to hundreds of teams in the near future. We started small and very intentional around scope, so that we could build a framework for rapid expansion.
- Forging New Ground: Our teams span across a vast landscape of products and purposes. In our discovery process, we found many supergraphs at various other organizations that were limited either in their scope or in the size of their graph development workforce. We needed to find a platform and also a vendor that would be willing to grow with us as we test the capabilities and limits of the supergraph concepts.
Where We Are Now
The success of our proof of concept convinced us of the value of federated GraphQL, and we decided to commit to this new approach. Many of the challenges listed above pointed to the need of some form of a governance team. Additionally, with there being some infrastructure setup and maintenance required to support Apollo federation (running the Apollo Router), our next step was to build a dedicated platform team around GraphQL at State Farm. This involved assembling a new team and laying down the foundational infrastructure to facilitate easy onboarding for development teams across the organization. This team is responsible for ensuring collaboration across engineering teams, maintaining a clean federated schema, management of any shared infrastructure, and continued advocacy for growing the supergraph. We additionally continue to work closely with Apollo and fully leverage their GraphOS product for our GraphQL federation journey. We have already put one use case into production that enables online customer channel business lines quoting and we have many more on the horizon.
Currently, our focus is on:
- Gaining Additional Adoption: We are actively promoting the benefits of federated GraphQL within State Farm and encouraging more teams to adopt this new approach. We have four more use cases we are onboarding onto our production supergraph along with actively attracting more.
- Increase Education and Training: GraphQL being new to so many areas of State Farm, our platform team is building an education and training plan that leverages self-paced materials and the Apollo Odyssey courses to get team’s up-to-speed.
- Building Out Automation: To streamline the development process, we are investing in automation for our GraphQL platform. This includes automated shared infrastructure deployments, automated schema validation, CI/CD pipelines for subgraphs, testing tools, and monitoring tools.
- Exploring Apollo Connectors for REST APIs: We are diving deep into a new feature called Apollo Connectors. This feature promises to further enhance our ability to integrate existing REST services into our federated graph seamlessly. One of the challenges we face is difficulty getting work prioritized when it involves another team. With Apollo Connectors, we see a large potential in the ability to grow our supergraph without impacting these teams. Streamlining supergraph development and showing a faster return is the goal.
The Future Holds Promise
Our journey with federated GraphQL is just beginning. As we continue to expand our GraphQL footprint at State Farm, we are excited about the possibilities that lie ahead. In the next six months, we expect to achieve significant growth and learning and plan to share our experiences, insights, and best practices with the community.
Stay tuned for more updates on our progress as we navigate this exciting transformation. Federated GraphQL has opened up new avenues for innovation at State Farm, and we look forward to seeing where it takes us.
To learn more about technology careers at State Farm, or to join our team visit, https://www.statefarm.com/careers.
Information contained in this article may not be representative of actual use cases. The views expressed in the article are personal views of the author and are not necessarily those of State Farm Mutual Automobile Insurance Company, its subsidiaries and affiliates (collectively “State Farm”). Nothing in the article should be construed as an endorsement by State Farm of any non-State Farm product or service.
<hr /><p>Adopting GraphQL Federation at State Farm — Our First Baby Steps was originally published in State Farm Engineering Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>