AS3: Consider documenting migration to graphql-ws in addition to how to preserve subscriptions-transport-ws

[glasser]

We should document how to migrate from "AS2 plus built-in subscriptions-transport-ws" to "AS3 plus your own subscriptions-transport-ws" for ease of upgrade, but we should evaluate if graphql-ws is a better solution for new users wanting to add subscriptions (without full Apollo Server integration, but that's not available with subscriptions-transport-ws either).

[glasser]

We are not going to document graphql-ws as the main recommendation for integration in AS3, even though it is more actively maintained than subscriptions-transport-ws. That's because it uses a new protocol. Using it also requires switching your Apollo Client to a link that works with it. More importantly, you can't use it from GraphQL Playground (though there are open PRs to support it) or from Apollo Explorer. This doesn't mean that graphql-ws isn't a good choice for people today, just that it might not be the best fit for detailed integration documentation.

We're hoping to bring subscription support to the Apollo platform in a more holistic and supported way sometime in the medium term future. Most likely we will choose the newer protocol/implementation when we do so, and we will at least link to it in the subscriptions docs, but for the moment it's not helpful to provide detailed docs on how to integrate with something when we're not also providing client-side support for the same library.

[enisdenjo]

Would like to point out that, due to the distinct subprotocol names, both GraphQL over WebSocket protocols can be supported in parallel.

For the server, you may consult the "ws server usage with subscriptions-transport-ws backwards compatibility" recipe to understand how.

And for the client, you simply can do a test-try connect to a server and check if the socket got closed with a 1002. Very similar to the GraphQL Playground graphql-ws support PR: graphql/graphql-playground#1326. However, I dont think that supporting both on the client side is really necessary. You can just either use the built-in, or provide your own WS link following the "Client usage with Apollo" recipe.

[glasser]

Fixed in #5406.

[glasser]

@enisdenjo Agreed! Right now we're in the final moments of putting an AS3 release out, and so backing up and making sure that various clients support the new protocol so we could document the new package as the recommended approach didn't make sense. That doesn't mean we don't want to support/encourage it and once more of the IDEs support it, we can revisit this.

[glasser]

Oops, forgot to include text about graphql-ws in the subscriptions page and not just the migration page. #5410