Workbench is a tool built by the Apollo Solutions Team to help design schemas using Apollo Federation and work with the composed results. This need was driven by working countless number of migrations from an existing GraphQL infrastructure (monolith or schema stitched) to an Apollo Federated architecture.
Head over to the docs to learn how you can use this tool.
- Install VS Code
- Install Apollo GraphQL VS Code Extension
- This is part of what makes intellisense work for writing schemas and queries
- Download the latest Apollo Workbench Release
- You can view past releases here
-
Open VS Code with any folder (a dialog will display if you don't have a folder open)
-
Go to your personal settings in Apollo Studio and copy your user api key. Paste your api key into the extension (which will be saved to your VS Code global state)
- Design a New Supergraph
- Migrating from Monolith to a New Supergraph
- Designing a change to an existing graph in Apollo Studio
To get the most out of GraphQL, your organization should expose a single data graph that provides a unified interface for querying any combination of your backing data sources. However, it can be challenging to represent an enterprise-scale data graph with a single, monolithic GraphQL server. Apollo Federation enables you to divide your graph's implementation across multiple composable services and Workbench is the tool to help you design that out with only schema files.
The Apollo Workbench extension for VS Code brings an all-in-one tooling experience for developing federated graphs.
- Creating and working with
.apollo-workbench
files - Mocking
.apollo-workbench
files- Supports remote URLs for any defined service
- Providing composition errors in Problems panel within VS Code
- Create and edit GraphQL operations for a loaded
.apollo-workbench
file - With a fully composed graph, view generated query plans for defined GraphQL operations
- Apollo Studio Integration
- Create a
.apollo-workbench
file from a graph that has been pushed into the schema registry (i.e.apollo service:push
) - Load GraphQL operations from a graph and add them to the loaded
.apollo-workbench
file.
- Create a
Apollo Workbench VS Code contains all the internals needed to mock the schemas you design out. Just click the play button for the design you want to start up and workbench takes care of the rest. You can also stop the mocks at anytime by just clicking the stop button (Hint: any design's stop button will stop the currently running mocks)
You may need to set specific headers that should be sent to the downstream services and you can set those by clicking on the settings "gear" icon for a service:
You can also set custom mocks per a service! Workbench currently only supports standard node packages and faker.js. If you want to see an example of a setup service, make a copy of the acephei-e-commerce
example graph after logging into Apollo Studio.
Composition errors in your designed schema will be written to the Problems panel in VS Code (you will see errors for any designs in the folder vs code has open):
Note: Since this is the beta release, some of the composition error pointers might be broken - like having the wrong range selected. All workbench.graphql
errors won't point at the correct file as the proper serviceName
needs to be identified. The error message should provide the details of what needs to be done. Stay tuned for more fixes in this area
If you have a valid fully composed schema, you should get intellisense when writing your queries with feedback in the Problems panel.
You can load all of the operations for a given graph into the Apollo Studio Graph Operations tree view by clicking on a graph in the Apollo Studio Graphs:
You may see some operations that have the same name, but different id
's next to them. This means the operations had different signatures and are different shapes. To load any operation into the current selected workbench, either right click the operation or press the plus button on the row:
Everytime you make a change to any operation in the current loaded workbench will try generating a new query plan for it. If you have a graph with composition errors, you'll need to resolve those composition errors before you can view the query plan of the given operatiion. To view the query plan, either right click the operation and select Open Query Plan or click the query plan icon in the row:
Apollo Workbench is maintained by the Apollo Developer Advocate Team with Michael Watson as the core maintainer/owner. Please feel free to open a GitHub issue on the repo with questions/issues/suggestions/feedback/just to say hi!
Also feel free to open an issue or PR and we'll try to evolve the tool to support designing a federated schema. There have been multiple additions to support mocking scenarios and we're very interested in hearing any ideas that might help with schema design.
The Apollo Solutions Team is considered Apollo's first customer and actually where Apollo Workbench first started. We work with our customers on their graph implementations and every organization has unique challenges (along with a lot of common ones). When these challenges surface, we sometimes build some tooling or example to solve that unique challenge. This could incorporate many elements of the various Apollo OSS libraries. If you're interested in learning more about the Apollo Solutions Team and an Enterprise relationship with Apollo, please reach out through our website.