chore(federation): Rename buildFederatedSchema -> buildSubgraphSchema (#915)

This deprecates but continues to support usages of buildFederatedSchema by exporting an
alias of the existing function.

Author: trevor-scheer

docs/source/api/apollo-federation.mdx

@@ -7,13 +7,14 @@ api_reference: true
 
 This API reference documents the exports from the `@apollo/federation` package.
 
-## `buildFederatedSchema`
+## `buildSubgraphSchema`
+> This method was renamed from `buildFederatedSchema` after @apollo/federation v0.28.0 (the previous name still works but might be removed in a future release).
 
 A function that takes an array of GraphQL schema modules and returns a federation-ready schema based on those modules:
 
 ```js{2}
 const server = new ApolloServer({
-  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }])
 });
 ```
 
@@ -83,13 +84,13 @@ const resolvers = {
 };
 
 const server = new ApolloServer({
-  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }])
 });
 ```
 
 ## `__resolveReference`
 
-The name of a special **reference resolver** function you can define for every [entity](../entities/) in a resolver map, _if_ that resolver map is part of a [federated schema](#buildfederatedschema).
+The name of a special **reference resolver** function you can define for every [entity](../entities/) in a resolver map, _if_ that resolver map is part of a [subgraph schema](#buildSubgraphSchema).
 
 The `__resolveReference` function enables your gateway's query planner to resolve a particular entity by whatever unique identifier your other subgraphs use to reference it. For details, see [Entities: Resolving](../entities/#resolving).
 

docs/source/migrating-from-stitching.md

@@ -43,14 +43,14 @@ If your implementing services use Apollo Server, add federation support to them
 npm install @apollo/federation
 ```
 
-Then use the `buildFederatedSchema` function to augment your schema with fields that are necessary for federation support:
+Then use the `buildSubgraphSchema` function to augment your schema with fields that are necessary for federation support:
 
 ```js
 const { ApolloServer } = require('apollo-server');
-const { buildFederatedSchema } = require('@apollo/federation');
+const { buildSubgraphSchema } = require('@apollo/federation');
 
 const server = new ApolloServer({
-  schema: buildFederatedSchema([
+  schema: buildSubgraphSchema([
     {
       typeDefs,
       resolvers,

docs/source/quickstart-pt-3.mdx

@@ -25,21 +25,21 @@ First, install the `@apollo/federation` library in your project:
 npm install @apollo/federation
 ```
 
-Next, import the `buildFederatedSchema` function in the file where you initialize `ApolloServer`:
+Next, import the `buildSubgraphSchema` function in the file where you initialize `ApolloServer`:
 
 ```js:title=index.js
-const { buildFederatedSchema } = require('@apollo/federation');
+const { buildSubgraphSchema } = require('@apollo/federation');
 ```
 
 Finally, modify your `ApolloServer` constructor by passing it a `schema` option instead of `typeDefs` and `resolvers`, like so:
 
 ```js:title=index.js
 const server = new ApolloServer({ 
-  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }])
 });
 ```
 
-(As shown, you now pass your `typeDefs` and `resolvers` to `buildFederatedSchema`.)
+(As shown, you now pass your `typeDefs` and `resolvers` to `buildSubgraphSchema`.)
 
 And that's it! You can now perform all of the same subgraph setup on your _own_ service (introspection, schema registration, etc.) that you did with the Apollo-hosted services we used in the first two parts. Refer to those parts for guidance.
 

docs/source/subgraphs.mdx

@@ -62,7 +62,7 @@ As part of our federated architecture, we want _other_ subgraphs to be able to e
 
 ```js:title=index.js
 const { ApolloServer, gql } = require('apollo-server');
-const { buildFederatedSchema } = require('@apollo/federation');
+const { buildSubgraphSchema } = require('@apollo/federation');
 
 const typeDefs = gql`
   type Query {
@@ -99,13 +99,13 @@ const resolvers = {
 
 > [Learn more about entities](./entities/)
 
-### Generating a federated schema
+### Generating a subgraph schema
 
-Finally, we use the `buildFederatedSchema` function from the `@apollo/federation` package to augment our schema definition with federation support. We provide the result of this function to the `ApolloServer` constructor:
+Finally, we use the `buildSubgraphSchema` function from the `@apollo/federation` package to augment our schema definition with federation support. We provide the result of this function to the `ApolloServer` constructor:
 
 ```js:title=index.js
 const server = new ApolloServer({
-  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }])
 });
 
 server.listen(4001).then(({ url }) => {
@@ -121,7 +121,7 @@ Here are the snippets above combined (again, note that for this sample to be com
 
 ```js:title=index.js
 const { ApolloServer, gql } = require('apollo-server');
-const { buildFederatedSchema } = require('@apollo/federation');
+const { buildSubgraphSchema } = require('@apollo/federation');
 
 const typeDefs = gql`
   type Query {
@@ -148,7 +148,7 @@ const resolvers = {
 }
 
 const server = new ApolloServer({
-  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }])
 });
 
 server.listen(4001).then(({ url }) => {
@@ -191,7 +191,7 @@ const server = new ApolloServer({
 
 ```js
 const { ApolloServer, gql, SchemaDirectiveVisitor } = require('apollo-server');
-const { buildFederatedSchema } = require ('@apollo/federation')
+const { buildSubgraphSchema } = require ('@apollo/federation')
 
 // typeDefs and resolvers defined here
 
@@ -205,7 +205,7 @@ class DeprecatedDirective extends SchemaDirectiveVisitor {
 const directives = {
   deprecated: DeprecatedDirective
 };
-let schema = buildFederatedSchema([{ typeDefs, resolvers }]);
+let schema = buildSubgraphSchema([{ typeDefs, resolvers }]);
 
 SchemaDirectiveVisitor.visitSchemaDirectives(schema, directives);
 

federation-js/CHANGELOG.md

@@ -4,11 +4,11 @@
 
 > The changes noted within this `vNEXT` section have not been released yet.  New PRs and commits which introduce changes should include an entry in this `vNEXT` section as part of their development.  When a release is being prepared, a new header will be (manually) created below and the appropriate changes within that release will be moved into the new section.
 
--_Nothing yet! Stay tuned_.
+- Rename `buildFederatedSchema` to `buildSubgraphSchema`. The previous name will continue to be supported but is deprecated. No functional change, usages of `buildFederatedSchema` should just be replaced with `buildSubgraphSchema`. [PR #915](https://github.com/apollographql/federation/pull/913)
 
 ## v0.28.0
 
-- When resolving the `Query._entities` field, honor `@cacheControl` directives on the object types that are members of the `_Entity` union. This feature is only enabled when your subgraph is running Apollo Server 3.0.2 or later. [PR #870](https://github.com/apollographql/apollo-server/pull/870) [Related docs PR](https://github.com/apollographql/apollo-server/pull/5536)
+- When resolving the `Query._entities` field, honor `@cacheControl` directives on the object types that are members of the `_Entity` union. This feature is only enabled when your subgraph is running Apollo Server 3.0.2 or later. [PR #870](https://github.com/apollographql/federation/pull/870) [Related docs PR](https://github.com/apollographql/apollo-server/pull/5536)
 
 ## v0.27.1
 

federation-js/README.md

@@ -8,7 +8,7 @@ For complete documentation, see the [Apollo Federation API reference](https://ww
 
 ```js
 const { ApolloServer, gql } = require("apollo-server");
-const { buildFederatedSchema } = require("@apollo/federation");
+const { buildSubgraphSchema } = require("@apollo/federation");
 
 const typeDefs = gql`
   type Query {
@@ -35,6 +35,6 @@ const resolvers = {
 };
 
 const server = new ApolloServer({
-  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+  schema: buildSubgraphSchema([{ typeDefs, resolvers }])
 });
 ```

federation-js/src/service/__tests__/buildFederatedSchema.test.ts renamed to federation-js/src/service/__tests__/buildSubgraphSchema.test.ts

@@ -1,6 +1,6 @@
 import gql from 'graphql-tag';
 import { Kind, graphql, DocumentNode, execute } from 'graphql';
-import { buildFederatedSchema } from '../buildFederatedSchema';
+import { buildSubgraphSchema } from '../buildSubgraphSchema';
 import { typeSerializer } from 'apollo-federation-integration-testsuite';
 
 expect.addSnapshotSerializer(typeSerializer);
@@ -10,9 +10,9 @@ const EMPTY_DOCUMENT = {
   definitions: [],
 };
 
-describe('buildFederatedSchema', () => {
+describe('buildSubgraphSchema', () => {
   it(`should mark a type with a key field as an entity`, () => {
-    const schema = buildFederatedSchema(gql`
+    const schema = buildSubgraphSchema(gql`
       type Product @key(fields: "upc") {
         upc: String!
         name: String
@@ -34,7 +34,7 @@ type Product {
   });
 
   it(`should mark a type with multiple key fields as an entity`, () => {
-    const schema = buildFederatedSchema(gql`
+    const schema = buildSubgraphSchema(gql`
       type Product @key(fields: "upc") @key(fields: "sku") {
         upc: String!
         sku: String!
@@ -58,7 +58,7 @@ type Product {
   });
 
   it(`should not mark a type without a key field as an entity`, () => {
-    const schema = buildFederatedSchema(gql`
+    const schema = buildSubgraphSchema(gql`
       type Money {
         amount: Int!
         currencyCode: String!
@@ -79,7 +79,7 @@ type Money {
         sdl
       }
     }`;
-    const schema = buildFederatedSchema(gql`
+    const schema = buildSubgraphSchema(gql`
       "A user. This user is very complicated and requires so so so so so so so so so so so so so so so so so so so so so so so so so so so so so so so so much description text"
       type User @key(fields: "id") {
         """
@@ -130,7 +130,7 @@ type User @key(fields: "id") {
 
   describe(`should add an _entities query root field to the schema`, () => {
     it(`when a query root type with the default name has been defined`, () => {
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Query {
           rootField: String
         }
@@ -149,7 +149,7 @@ type Query {
     });
 
     it(`when a query root type with a non-default name has been defined`, () => {
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         schema {
           query: QueryRoot
         }
@@ -173,7 +173,7 @@ type QueryRoot {
   });
   describe(`should not add an _entities query root field to the schema`, () => {
     it(`when no query root type has been defined`, () => {
-      const schema = buildFederatedSchema(EMPTY_DOCUMENT);
+      const schema = buildSubgraphSchema(EMPTY_DOCUMENT);
 
       expect(schema.getQueryType()).toMatchInlineSnapshot(`
 type Query {
@@ -182,7 +182,7 @@ type Query {
 `);
     });
     it(`when no types with keys are found`, () => {
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Query {
           rootField: String
         }
@@ -196,7 +196,7 @@ type Query {
 `);
     });
     it(`when only an interface with keys are found`, () => {
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Query {
           rootField: String
         }
@@ -233,7 +233,7 @@ type Query {
         ],
       };
 
-      const schema = buildFederatedSchema([
+      const schema = buildSubgraphSchema([
         {
           typeDefs: gql`
             type Product @key(fields: "upc") {
@@ -287,7 +287,7 @@ type Query {
         ],
       };
 
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Product @key(fields: "upc") {
           upc: Int
           name: String
@@ -311,7 +311,7 @@ type Query {
         sdl
       }
     }`;
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Review {
           id: ID
         }
@@ -346,7 +346,7 @@ type Review {
       sdl
     }
   }`;
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Review {
           id: ID
         }
@@ -388,7 +388,7 @@ type Review {
         sdl
       }
     }`;
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Product @key(fields: "upc") {
           upc: String!
           name: String
@@ -411,7 +411,7 @@ type Review {
         sdl
       }
     }`;
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Product @key(fields: "upc") @key(fields: "name") {
           upc: String!
           name: String
@@ -436,7 +436,7 @@ type Review {
         }
       }`;
 
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         type Review @key(fields: "id") {
           id: ID!
           body: String
@@ -483,7 +483,7 @@ extend type User @key(fields: "email") {
         }
       }`;
 
-      const schema = buildFederatedSchema(gql`
+      const schema = buildSubgraphSchema(gql`
         directive @custom on FIELD
 
         extend type User @key(fields: "email") {
@@ -530,7 +530,7 @@ describe('legacy interface', () => {
     `,
   ];
   it('allows legacy schema module interface as an input with an array of typeDefs and resolvers', async () => {
-    const schema = buildFederatedSchema({ typeDefs, resolvers });
+    const schema = buildSubgraphSchema({ typeDefs, resolvers });
     expect(schema.getType('_Entity')).toMatchInlineSnapshot(
       `union _Entity = Product`,
     );
@@ -553,7 +553,7 @@ describe('legacy interface', () => {
     });
   });
   it('allows legacy schema module interface as a single module', async () => {
-    const schema = buildFederatedSchema({
+    const schema = buildSubgraphSchema({
       typeDefs: gql`
         type Query {
           product: Product
@@ -588,7 +588,7 @@ describe('legacy interface', () => {
     });
   });
   it('allows legacy schema module interface as a single module without resolvers', async () => {
-    const schema = buildFederatedSchema({
+    const schema = buildSubgraphSchema({
       typeDefs: gql`
         type Query {
           product: Product
@@ -612,7 +612,7 @@ type Product {
     );
   });
   it('allows legacy schema module interface as a simple array of documents', async () => {
-    const schema = buildFederatedSchema({ typeDefs });
+    const schema = buildSubgraphSchema({ typeDefs });
     expect(schema.getType('Product')).toMatchInlineSnapshot(`
 type Product {
   upc: String!

federation-js/src/service/buildFederatedSchema.ts renamed to federation-js/src/service/buildSubgraphSchema.ts

@@ -28,7 +28,7 @@ type LegacySchemaModule = {
 
 export { GraphQLSchemaModule };
 
-export function buildFederatedSchema(
+export function buildSubgraphSchema(
   modulesOrSDL:
     | (GraphQLSchemaModule | DocumentNode)[]
     | DocumentNode
@@ -38,9 +38,9 @@ export function buildFederatedSchema(
   // map of resolvers to build a schema. Long term we don't want to support this
   // style anymore as we move towards a more structured approach to modules,
   // however, it has tripped several teams up to not support this signature
-  // in buildFederatedSchema. Especially as teams migrate from
+  // in buildSubgraphSchema. Especially as teams migrate from
   // `new ApolloServer({ typeDefs: DocumentNode[], resolvers })` to
-  // `new ApolloServer({ schema: buildFederatedSchema({ typeDefs: DocumentNode[], resolvers }) })`
+  // `new ApolloServer({ schema: buildSubgraphSchema({ typeDefs: DocumentNode[], resolvers }) })`
   //
   // The last type in the union for `modulesOrSDL` supports this "legacy" input
   // style in a simple manner (by just adding the resolvers to the first typeDefs entry)
@@ -132,3 +132,8 @@ export function buildFederatedSchema(
 
   return schema;
 }
+
+/**
+ * @deprecated Use `buildSubgraphSchema` instead.
+ */
+export const buildFederatedSchema = buildSubgraphSchema;