Agree on graphQL playground

[LukSteib]

Goal

Agree on the graphQL playground we will use to embed in UI

Context

The Switchboard API should come with a playground and interface that allows for easy usage. Reference project used appollo studio. However we want to provide a self hostable and open source solution.

Tasks

• List criteria
• Benchmark currently used playground against criteria
• (optional) propose alternative contenders
• Get feedback from SES based on staging deployment (depends on Setup staging switchboard#30)

[LukSteib]

Criteria for playground

• self hostable and open source
• Export to JSON (file)
• Export to CSV
• Tabular view of the return value
• Creating queries and mutations by clicking on fields
• Creating filters by clicking on fields
• Changelog

[valiafetisov]

Before we proceed researching other explorers, I would thoroughly checked if Apollo Explorer might actually suit our needs.

It seems that Apollo Explorer is open-source, MIT-licensed frontend-only part of the closed-source Apollo Studio cloud service. According to the docs, the Explorer can be embedded into other websites, but the misleading (and also annoying) part of the embed is the header with logo + login button on top (which suggests and advertises that you need to have Apollo Studio account in order to use it). Therefore, before proceeding to research other options:

• Investigate if @apollo/explorer can be embedded into our website
• Investigate if the header with logo and login button can be removed via plugin settings or via a fork
• Confirm that the embed does not need to depend on the Apollo Studio and does not send any requests to their servers
• Investigate if the functionality outlined above is still available

[valiafetisov]

Apollo Explorer

Despite the @apollo/explorer package being MIT-licensed, all it does is: verifies configuration parameters and creates iframe that points to their server:

The iframe contains apollo logo, header with login button and cookies consent (and tries to send all kinds of tracking requests):

Conclusion

We can't use Apollo Explorer due to its centralisation. I wouldn't even consider it as a centralised backstop as it interferes with our UI (via misleading login button). Users who prefer to use Apollo (or any other private/desktop-based explorer) would still able to use it via their deployed version, since we plan to keep graphql schema introspection enabled in production.

Takeaways

• Disable Apollo Explorer on the API-level, as it's enabled by default

[valiafetisov]

Currently used explorer is Graphql Playground from the original graphql organisation. It's build on top of the GraphiQL explorer (so it has even less features). Other open-source alternatives include:

• graphql-explorer (more like a simple UI over queries and mutations derived from introspection)
  • I think something similar but with better UX (for non-technical people) can be easily build using introspection query
• altair – another competing IDE
  • Can be added via altair-express-middleware package
  • Can be previeved online via https://altair-gql.sirmuel.design/
  • Seems to also have "account" button, but less visible

Criteria	Apollo Explorer	Graphql Playground	GraphiQL	Altair
self hostable and open source	No	Yes, MIT	Yes, MIT	Yes, MIT
Export to JSON (file)	Yes	No	No	No
Export to CSV	Yes	No	No	No
Tabular view of the return value	Yes	No	No	No
Creating queries and mutations by clicking on fields	Yes	No, but autocompleted	No	Possible via clicking on "ADD QUERY" button in the docs
Creating filters by clicking on fields	Yes	No	No	No
Changelog	Yes	No	No	No

Conclusion

We can switch to Altair since it seems to have a little bit better UX, but will first need to figure out how to disable accounts feature. Otherwise, current Graphql Playground seems to be a solid choice from the existing options