Compose a supergraph and get the API schema

[smyrick]

Description

When I compose a supergraph with rover supergraph compose I get the GraphQL schema that includes all the Federation directives and internals. This schema is what is passed to Router to run the gateway, however clients will see a slimmed down version of this schema when running introspection that we call the "API Schema". This API Schema and the Supergraph Schema are actually different types of documents and might have slightly different fields and information (see fields marked with @inaccessible).

As a client developer I SHOULD be using the API schema to do my type generation, rather than the supergraph schema. If I want to get this API schema today I can:

• I have to compose and pass a supergraph to a router and do introspection . You could automate this a bit with rover dev but it is not ideal
• Publish and compose my schema with GraphOS and then run rover graph fetch instead of rover supergraph fetch which returns the API schema

Instead a rover command to run locally would be nice:

# New command or flag
rover supergraph apiSchema --supergraph-schema prod-schema.graphql

Notes

The function to do this lives in a couple places

• Internal JS composition: https://github.com/apollographql/federation/blob/9a2eaf2ceb1d001b8d83cedf7a2245b1429e1386/internals-js/src/definitions.ts#L1272-L1296
• Internal Router code: https://github.com/apollographql/router/blob/2a1492f244ce3d6eba0f34e0584925d1f6e8385b/apollo-federation/src/api_schema.rs#L113-L116

[LongLiveCHIEF]

@smyrick so if I understand correctly, you're thinking that normally the command below produces SDL output:

rover supergraph compose --config ./supergraph.yaml --output prod-schema.graphql

But by adding the apiSchema it would change that to be an api schema output?

rover supergraph compose --config ./supergraph.yaml --apiSchema --output prod-schema.graphql

...or are you thinking it would output both?

[smyrick]

@LongLiveCHIEF I guess it could output both or maybe there is even a separate command that takes the Supergraph Schema as input and gives you the API schema, but as a client developer today I want some automated way to get the API schema so I can use that to generate my types. If you use the supergraph schema today it technically can work as you don't need to worry about most supergraph metadata directive, however there are some features like @inaccessible that might be showing extra stuff that is not visible in the API schema compared to the Supergraph and that might also change in the future too

• Command to pass in supergraph as input

rover supergraph api --supergraph-schema prod-schema.graphql --out prod-api-schema.graphql

[LongLiveCHIEF]

You would probably also want to consider the ability to specify contracts in this case.