As a startup, it's important to ensure that our API documentation is accurate, up-to-date, and easily accessible to our customers. The documentation must help our customers clearly understand how our API works and how they can work with it.
One way to make it easier for our customers to work with our API is by providing a GraphQL API explorer directly in our documentation. This allows developers to easily explore the API schema, experiment with different queries, and see the responses in real time, all from within the same documentation. This way we can reduce the learning curve and increase the adoption of our API.
When we were looking for a GraphQL API explorer to include in our API documentation, we had several requirements in mind to ensure that it would be a good fit for our needs. Here are some of the requirements we had:
Basing on those requirements we needed to find a solution that would meet all of our requirements and offer additional benefits for our GraphQL Explorer.
When weighing our options for a GraphQL API explorer, we considered both GraphiQL and Apollo Studio. GraphiQL, being the original GraphQL explorer, had the advantage of being widely used and well-documented. On the other hand, Apollo Studio offered a more polished UI, better state persistence, and seamless integration with Apollo Server.
Our initial approach was to find a way to embed our public ApolloStudio using an iframe. During our research, we discovered that Apollo Studio offers an easy solution to embed the explorer with a React component, the ApolloExplorer. We decided to give it a try, and it turned out to be a perfect fit for our needs.
This React component allowed us to easily set up our explorer pointing to our schema, with all the props we required to make it fit our docs theme. Just in a few lines of code.
In order for our GraphQL queries to work, we require passing three headers to each request.
For this, we gave the user the option to sign into Propel and two dropdowns to select an account and an environment. But, how can we sync this with the ApolloExplorer?
Fortunately, the ApolloExplorer component provides an easy way to pass a request handler via props using the <span class="code-exp">handleRequest</span> prop
We can now use the account and environment headers with the values provided by our dropdowns!
Our last challenge was allowing the user to have a fullscreen version of the explorer, so after checking for an option to turn the ApolloExplorer fullscreen we found that the best approach was making a component on top of the ApolloExplorer component and reusing it, but since those would be separate, how can we ensure we keep the same state between the small and the fullscreen version?
ApolloExplorer provides a prop called <span class="code-exp">persistExplorerState</span> this prop saves the entire explorer state including variables, and the built GraphQL document in local storage. This way, both versions can feed from the storage and keep the same state
Integrating Apollo Studio with our Propel API documentation has been a great success. By using the ApolloExplorer React component, we were able to easily embed the GraphQL API explorer with our Docusaurus documentation, providing our customers with a polished and easy-to-use UI.
Additionally, we were able to pass custom request headers to the explorer and seamlessly switch between fullscreen and small versions.
Our customers building high-performance data products with Propel's API benefit greatly from this integration. It’s their go-to development tool.
If you’d like to play around with Propel’s GraphQL Explorer, check it out in our docs.
How we built Propel
Apollo Server 3 is officially deprecated, so it’s time to upgrade to Apollo Server 4. This post explains the expected and unexpected changes