How we integrated Apollo Studio with the Propel API docs

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.

Our requirements for the GraphQL Explorer

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:

1. Intuitive UI: We wanted an explorer with an intuitive and user-friendly UI that would be easy to use, even if they were new to GraphQL. The UI should be clear and concise, allowing the user to clearly explore the schema and run their queries.
2. State persistence: We wanted a GraphQL API explorer that would persist the state of the explorer between sessions, allowing developers to easily modify and refine their queries over time without easily losing their progress.
3. Easy integration: Finally, we wanted an explorer that would be easy to integrate with our documentation platform based on Docusaurus. We didn't want to have to spend a lot of time customizing or configuring the explorer to work in our docs.

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.

GraphiQL vs. Apollo Studio

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.

Challenges we faced

IFrame vs. React embeddable

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.

<ApolloExplorer
  className={styles.explorer}
  graphRef="Propel-API@production"
  initialState={{ displayOptions: { theme } }}
/>

Passing custom request headers

In order for our GraphQL queries to work, we require passing three headers to each request.

• Authorization: contains the Propel account’s bearer access token.
• X-Pro-Account: The Propel account’s id.
• X-Pro-Environment: The Propel account’s environment where the user is pointing.

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

<ApolloExplorer
  className={styles.explorer}
  graphRef="Propel-API@production"
  initialState={{ displayOptions: { theme } }}
  handleRequest={(url, options) => {
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'X-Pro-Account': currentAccount,
        'X-Pro-Environment': currentEnvironment,
        Authorization: `Bearer ${accessToken}`
      }
    })
  }}
/>

We can now use the account and environment headers with the values provided by our dropdowns!

Fullscreen version and state persistence

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

<ApolloExplorer
  className={styles.explorer}
  graphRef="Propel-API@production"
  persistExplorerState
  initialState={{ displayOptions: { theme } }}
  handleRequest={(url, options) => {
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'X-Pro-Account': currentAccount,
        'X-Pro-Environment': currentEnvironment,
        Authorization: `Bearer ${accessToken}`
      }
    })
  }}
/>

Conclusion

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.