RFC: rename stitch package to "gateway" in Tools v7

[gmac]

Schema stitching has a long a sorted history, and the past six months have ushered in a whole new era for it. Thus, I'd propose this as a good juncture to change the moniker in a way that helps developers easily recognize its potential. This update could have a simple two-step upgrade path:

1. Switch @graphql-tools/stitch to @graphql-tools/gateway package.
2. Change stitchSchemas to makeGatewaySchema (or something along those lines).

Here's why I think this would be prudent:

• Stitching originates within the Apollo ecosystem and still has woefully outdated docs there, yet is the top Google search result for "schema stitching". These Apollo docs include several notes like: "if you require this functionality, it would be better if you use Apollo Federation.". Like it or not, stitching is getting its lunch money stolen.

• The second Google search result for "schema stitching" is the migration guide for upgrading to Federation. There's clear air here that stitching is the "old" way to do this–which is no longer applicable by any metric thanks to recent feature work.

• Then let's say I have no prior knowledge of any platforms. I just know I need to build some kind of front door to my API, and I hear people talking about "gateway" apps. Researching my options, I wouldn't recognize a bespoke-sounding library like "stitching" to be highly relevant to my needs. I kind of know what a "gateway" is by name alone, but I don't know what "stitching" is until I understand what it does. This name parity with the Apollo counterpart would go a long way for prospective devs who are window shopping options.

• Also internally within Tools, there's a lot of confusion over the goals of mergeSchemas and stitchSchemas... compounded by the fact that mergeSchemas IS the old version of stitching. This gateway shift would help I think: mergeSchemas would be more obvious as a basic library tool for combining SDLs (merging resolvers and schemas could be greatly downplayed there), while makeGatewaySchema would be a lot more direct about its intention to provide gateway tools for a consolidated API.

Anyway, just thinking out loud there. @yaacovCR – thoughts?

[yaacovCR]

A stitched schema can be a gateway schema only, but it can also have local types in addition.... Is there a confusion point there?

[yaacovCR]

Basically, I think we need a grand reopening, but I would rather reclaim the stitching moniker than get a new one...

Maybe easier said than done...

@ardatan @Urigo what do you think?

[gmac]

On the local schema question – I don't feel that's contentious... it'd be extremely limiting if a gateway package had no options for communicating with local resources. Apollo is actually way behind on their documentation about this. Shoot, I can't find the original github issue now, but an Apollo maintainer had famously replied saying that, "yes, LocalGraphQLDataSource officially exists but we've never gotten around to documenting it". The Apollo gateway's local resource feature is now known through unofficial documentation.

[gmac]

All told – a "gateway" is really just a thing in front of many things that all incoming traffic passes through. It doesn't really matter what the many things are.

[gmac]

Also worth noting... I was just throwing this out there as an idea (I intended RFC as "request for consideration"). I hope my case didn't come off too strongly to be read as an attack on the package design! I don't have super strong feelings here or any real intention to press the case.

[yaacovCR]

Oh, definitely not!

Thanks for the RFC, hopefully when @ardatan or others from the guild or any other interested parties have time they can weigh in.

[yaacovCR]

See #1935

[yaacovCR]

Timely!

[yaacovCR]

I think we made the right choice in trying to rehabilitate stitching term. As well as separation between what schema stitching is within graphql-tools, ie creation of new schema, and the gateway server, which serves the stitched schema. But, we shall see what v8 brings...