Reload Docs on Refresh / Application Load

[benhutton]

Is your feature request related to a problem? Please describe.
It gets annoying to have to reload the docs manually right after opening the tool. What we expect is that if we just opened the tool, the docs are up to date!

Describe the solution you'd like
Add a configuration option called "reload docs on load" or something like that. When that option is checked, every time we load the app, it attempts to reload the docs.

Describe alternatives you've considered
Right now, we just reload docs manually.

The schema auto refresh functionality is a bit more powerful and involved than we need.

What we're proposing is a middle ground between those two states.

[welcome]

👋🏾Thanks for opening your first issue here! Be sure to follow the issue template! ✌🏾

[imolorhe]

Why do you need to reload the schema on app load? The schema should be stored locally so there shouldn't be a need to request it from the server again.

[benhutton]

@imolorhe because our schema changes regularly, so the locally stored schema is out of date

[imolorhe]

How frequently? Refreshing the docs on app load might not be sufficient for your needs. Perhaps you would want to have the schema polling implementation as a fallback for the current autorefresh functionality instead (that obviously has worse performance than the current autorefresh functionality).

[benhutton]

We update between a handful of times a day and a handful of times a week, at our current phase of development.

I know that refreshing docs on app load won't solve every problem. I think what I'm trying to say isn't that it would solve all of our schema reloading problems, but that it will make the app behave like we expect it to: if we load the app up, it has a new schema. If we refresh the entire app, it has a new schema. We'll definitely need to occasionally refresh the schema manually.

Polling feels like overkill for us right now, though maybe I'm not understanding what all is available. What is the "schema polling implementation"? Is that what we're talking about now, or something that already exists?

[imolorhe]

Yes, the schema polling would poll your server for the schema constantly in a given interval.

I do not think there is an expectation for the schema to be fresh when the app is loaded, given that the schema is only fetched when the user requests it (by specifying the endpoint, or clicking the reload button). The only exception to that rule is when you have the autorefresh implemented, and there is an indication that the app is connected to your server and the schema should be up to date.

I have a hesitation to implement the schema refresh on app load because I fail to see it actually solving any real issues. Like you said in your case, the refresh on app load wouldn't resolve the issue requiring you to manually reload the docs at different times, because Altair still doesn't know when the schema has been updated in the server for it to fetch the new schema.

As such, the only middleground solution I can think of at the moment is that of polling, which should resolve the case of the schema freshness. I am open to hear any other suggestions you might have, or if you still think the doc refresh on app load is still an important feature, I'd like to know why 🙂

[benhutton]

@imolorhe thanks for being willing to hear me out. We really love your tool and appreciate all the hard work you put into it!

I should clarify something: in our particular use case, we are serving altair off of our graphql server, and that particular altair instance is used only for that particular graphql server. We are not connecting one altair instance to multiple graphql endpoints. Just one. SO, when you talk about "the app is connected to your server", for our mental model, that is in fact the case.

To go along with that, we are running it as a web app, in a browser, with a refresh button. The disconnect is that the browser refresh button isn't doing what we want it to. The in-app refresh button be fully sufficient when you're using the non-browser versions of Altair, but when its in a browser, it's weird for the browser refresh not to trigger a refresh.

I do not think there is an expectation for the schema to be fresh when the app is loaded,

My point is that for the team I support, there is that expectation. I have frustrated users because that behavior is not in place.

I do not think there is an expectation for the schema to be fresh when the app is loaded, given that the schema is only fetched when the user requests it.

The expectation isn't created by an understanding of what the app's current design is, but an expectation about how a browser refresh button should work. We expect refresh to refresh. And it doesn't.

Gmail's web interface has a refresh button that you can click to trigger an immediate refresh of your email data. But also when you refresh the browser, you get refreshed data at the same time. You don't need to click that refresh button OR wait for polling.

[imolorhe]

It really sounds like your server would benefit from implementing the GraphQL event stream 😄 https://sirmuel.design/a-better-graphql-developer-experience-with-x-graphql-event-stream-1256aef96f24

With this implemented, you get the behavior you get from Gmail (it just updates without doing anything), and Altair already supports this. You probably already knew this though 😏

It sounds like you still click a button (the browser refresh button). Would it make sense if I said you could click the reload button in Altair instead of the browser refresh button (there are also keyboard shortcuts available Ctrl+Shift+R)?

I should clarify something: in our particular use case, we are serving altair off of our graphql server,

😍 ^^ Awesome!

We are not connecting one altair instance to multiple graphql endpoints.

Even when served from a server, Altair can still work with requests across domains, at least as far as the implementation of Altair is concerned, there's no way to limit an Altair instance to a specific endpoint.

In conclusion

If you want to provide your users with the seamless "always-fresh" experience (the Gmail experience), you can do that using the GraphQL event stream implementation that Altair already supports. That would be the best experience for your users, but it would require a bit more development effort from you as the developer.

I'll add an option to refresh the schema on app load. While I'm still not convinced it's the best approach, I wouldn't not add it if there's a use case for it.

Medium

A better GraphQL developer experience with ‘X-GraphQL-Event-Stream’

TL;DR — Implementing X-GraphQL-Event-Stream header in your server allows GraphQL IDEs like Altair to update your schema without you having…

[benhutton]

@imolorhe thanks, I appreciate it!