feat(appsync): separating schema from graphql api

packages/@aws-cdk/aws-appsync/README.md

@@ -47,8 +47,7 @@ import * as db from '@aws-cdk/aws-dynamodb';
 
 const api = new appsync.GraphQLApi(stack, 'Api', {
   name: 'demo',
-  schemaDefinition: appsync.SchemaDefinition.FILE,
-  schemaDefinitionFile: join(__dirname, 'schema.graphql'),
+  schema: appsync.Schema.fromAsset(join(__dirname, 'schema.graphql')),
   authorizationConfig: {
     defaultAuthorization: {
       authorizationType: appsync.AuthorizationType.IAM
@@ -83,7 +82,53 @@ demoDS.createResolver({
 });
 ```
 
-## Imports
+### Schema
+
+Every GraphQL Api needs a schema to define the Api. CDK offers `appsync.Schema`
+for static convenience methods for various types of schema declaration: code-first
+or schema-first.
+
+#### Code-First
+
+When declaring your GraphQL Api, CDK defaults to a code-first approach if the
+`schema` property is not configured. 
+
+```ts
+const api = new appsync.GraphQLApi(stack, 'api', { name: 'myApi' });
+```
+
+CDK will declare a `Schema` class that will give your Api access functions to
+define your schema code-first: `addType`, `addObjectType`, `addToSchema`, etc.
+
+You can also declare your `Schema` class outside of your CDK stack, to define
+your schema externally.
+
+```ts
+const schema = new appsync.Schema();
+schema.addObjectType('demo', {
+  definition: { id: appsync.GraphqlType.id() },
+});
+const api = new appsync.GraphQLApi(stack, 'api', {
+  name: 'myApi',
+  schema
+});
+```
+
+See the [code-first schema](#Code-First-Schema) section for more details.
+
+#### Schema-First
+
+You can define your GraphQL Schema from a file on disk. For convenience, use
+the `appsync.Schema.fromAsset` to specify the file representing your schema.
+
+```ts
+const api = appsync.GraphQLApi(stack, 'api', {
+  name: 'myApi',
+  schema: appsync.Schema.fromAsset(join(__dirname, 'schema.graphl')),
+});
+```
+
+### Imports
 
 Any GraphQL Api that has been created outside the stack can be imported from 
 another stack into your CDK app. Utilizing the `fromXxx` function, you have 
@@ -101,7 +146,7 @@ If you don't specify `graphqlArn` in `fromXxxAttributes`, CDK will autogenerate
 the expected `arn` for the imported api, given the `apiId`. For creating data 
 sources and resolvers, an `apiId` is sufficient.
 
-## Permissions
+### Permissions
 
 When using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role
 with correct permissions must be used for access to API.
@@ -153,7 +198,7 @@ const api = new appsync.GraphQLApi(stack, 'API', {
 api.grant(role, appsync.IamResource.custom('types/Mutation/fields/updateExample'), 'appsync:GraphQL')
 ```
 
-### IamResource
+#### IamResource
 
 In order to use the `grant` functions, you need to use the class `IamResource`.
 
@@ -163,7 +208,7 @@ In order to use the `grant` functions, you need to use the class `IamResource`.
 
 - `IamResource.all()` permits ALL resources.
 
-### Generic Permissions
+#### Generic Permissions
 
 Alternatively, you can use more generic `grant` functions to accomplish the same usage.
 
@@ -280,7 +325,6 @@ import * as schema from './object-types';
 
 const api = new appsync.GraphQLApi(stack, 'Api', {
   name: 'demo',
-  schemaDefinition: appsync.SchemaDefinition.CODE,
 });
 
 this.objectTypes = [ schema.Node, schema.Film ];
@@ -294,13 +338,12 @@ api.addType('Query', {
       args: schema.args,
       requestMappingTemplate: dummyRequest,
       responseMappingTemplate: dummyResponse,
-    },
+    }),
   }
-  });
-})
+});
 
-this.objectTypes.map((t) => api.appendToSchema(t));
-Object.keys(filmConnections).forEach((key) => api.appendToSchema(filmConnections[key]));
+this.objectTypes.map((t) => api.addType(t));
+Object.keys(filmConnections).forEach((key) => api.addType(filmConnections[key]));
 ```
 
 Notice how we can utilize the `generateEdgeAndConnection` function to generate
@@ -457,7 +500,6 @@ You can create Object Types in three ways:
     ```ts
     const api = new appsync.GraphQLApi(stack, 'Api', {
       name: 'demo',
-      schemaDefinition: appsync.SchemaDefinition.CODE,
     });
     const demo = new appsync.ObjectType('Demo', {
       defintion: {
@@ -466,7 +508,7 @@ You can create Object Types in three ways:
       },
     });
 
-    api.appendToSchema(object.toString());
+    api.addType(object);
     ```
     > This method allows for reusability and modularity, ideal for larger projects. 
     For example, imagine moving all Object Type definition outside the stack.
@@ -490,7 +532,7 @@ You can create Object Types in three ways:
     `cdk-stack.ts` - a file containing our cdk stack
     ```ts
     import { demo } from './object-types';
-    api.appendToSchema(demo.toString());
+    api.addType(demo);
     ```
 
 2. Object Types can be created ***externally*** from an Interface Type.
@@ -513,7 +555,6 @@ You can create Object Types in three ways:
     ```ts
     const api = new appsync.GraphQLApi(stack, 'Api', {
       name: 'demo',
-      schemaDefinition: appsync.SchemaDefinition.CODE,
     });
     api.addType('Demo', {
       defintion: {

packages/@aws-cdk/aws-appsync/lib/graphqlapi.ts

@@ -1,10 +1,10 @@
-import { readFileSync } from 'fs';
 import { IUserPool } from '@aws-cdk/aws-cognito';
 import { ManagedPolicy, Role, ServicePrincipal, Grant, IGrantable } from '@aws-cdk/aws-iam';
 import { CfnResource, Construct, Duration, IResolvable, Stack } from '@aws-cdk/core';
 import { CfnApiKey, CfnGraphQLApi, CfnGraphQLSchema } from './appsync.generated';
 import { IGraphqlApi, GraphqlApiBase } from './graphqlapi-base';
-import { ObjectType, ObjectTypeProps } from './schema-intermediate';
+import { Schema } from './schema';
+import { IIntermediateType } from './schema-base';
 
 /**
  * enum with all possible values for AppSync authorization type
@@ -201,21 +201,6 @@ export interface LogConfig {
   readonly fieldLogLevel?: FieldLogLevel;
 }
 
-/**
- * Enum containing the different modes of schema definition
- */
-export enum SchemaDefinition {
-  /**
-   * Define schema through functions like addType, addQuery, etc.
-   */
-  CODE = 'CODE',
-
-  /**
-   * Define schema in a file, i.e. schema.graphql
-   */
-  FILE = 'FILE',
-}
-
 /**
  * Properties for an AppSync GraphQL API
  */
@@ -242,18 +227,13 @@ export interface GraphQLApiProps {
   /**
    * GraphQL schema definition. Specify how you want to define your schema.
    *
-   * SchemaDefinition.CODE allows schema definition through CDK
-   * SchemaDefinition.FILE allows schema definition through schema.graphql file
+   * Schema.fromFile(filePath: string) allows schema definition through schema.graphql file
    *
-   * @experimental
-   */
-  readonly schemaDefinition: SchemaDefinition;
-  /**
-   * File containing the GraphQL schema definition. You have to specify a definition or a file containing one.
+   * @default - schema will be generated code-first (i.e. addType, addObjectType, etc.)
    *
-   * @default - Use schemaDefinition
+   * @experimental
    */
-  readonly schemaDefinitionFile?: string;
+  readonly schema?: Schema;
   /**
    * A flag indicating whether or not X-Ray tracing is enabled for the GraphQL API.
    *
@@ -390,9 +370,9 @@ export class GraphQLApi extends GraphqlApiBase {
   public readonly name: string;
 
   /**
-   * underlying CFN schema resource
+   * the schema attached to this api
    */
-  public readonly schema: CfnGraphQLSchema;
+  public readonly schema: Schema;
 
   /**
    * the configured API key, if present
@@ -401,9 +381,9 @@ export class GraphQLApi extends GraphqlApiBase {
    */
   public readonly apiKey?: string;
 
-  private schemaMode: SchemaDefinition;
+  private schemaResource: CfnGraphQLSchema;
   private api: CfnGraphQLApi;
-  private _apiKey?: CfnApiKey;
+  private apiKeyResource?: CfnApiKey;
 
   constructor(scope: Construct, id: string, props: GraphQLApiProps) {
     super(scope, id);
@@ -429,16 +409,16 @@ export class GraphQLApi extends GraphqlApiBase {
     this.arn = this.api.attrArn;
     this.graphQlUrl = this.api.attrGraphQlUrl;
     this.name = this.api.name;
-    this.schemaMode = props.schemaDefinition;
-    this.schema = this.defineSchema(props.schemaDefinitionFile);
+    this.schema = props.schema ?? new Schema();
+    this.schemaResource = this.schema.bind(this);
 
     if (modes.some((mode) => mode.authorizationType === AuthorizationType.API_KEY)) {
       const config = modes.find((mode: AuthorizationMode) => {
         return mode.authorizationType === AuthorizationType.API_KEY && mode.apiKeyConfig;
       })?.apiKeyConfig;
-      this._apiKey = this.createAPIKey(config);
-      this._apiKey.addDependsOn(this.schema);
-      this.apiKey = this._apiKey.attrApiKey;
+      this.apiKeyResource = this.createAPIKey(config);
+      this.apiKeyResource.addDependsOn(this.schemaResource);
+      this.apiKey = this.apiKeyResource.attrApiKey;
     }
   }
 
@@ -515,7 +495,7 @@ export class GraphQLApi extends GraphqlApiBase {
    * @param construct the dependee
    */
   public addSchemaDependency(construct: CfnResource): boolean {
-    construct.addDependsOn(this.schema);
+    construct.addDependsOn(this.schemaResource);
     return true;
   }
 
@@ -584,29 +564,6 @@ export class GraphQLApi extends GraphqlApiBase {
     });
   }
 
-  /**
-   * Define schema based on props configuration
-   * @param file the file name/s3 location of Schema
-   */
-  private defineSchema(file?: string): CfnGraphQLSchema {
-    let definition;
-
-    if ( this.schemaMode === SchemaDefinition.FILE && !file) {
-      throw new Error('schemaDefinitionFile must be configured if using FILE definition mode.');
-    } else if ( this.schemaMode === SchemaDefinition.FILE && file ) {
-      definition = readFileSync(file).toString('utf-8');
-    } else if ( this.schemaMode === SchemaDefinition.CODE && !file ) {
-      definition = '';
-    } else if ( this.schemaMode === SchemaDefinition.CODE && file) {
-      throw new Error('definition mode CODE is incompatible with file definition. Change mode to FILE/S3 or unconfigure schemaDefinitionFile');
-    }
-
-    return new CfnGraphQLSchema(this, 'Schema', {
-      apiId: this.apiId,
-      definition,
-    });
-  }
-
   /**
    * Escape hatch to append to Schema as desired. Will always result
    * in a newline.
@@ -617,31 +574,18 @@ export class GraphQLApi extends GraphqlApiBase {
    *
    * @experimental
    */
-  public appendToSchema(addition: string, delimiter?: string): void {
-    if ( this.schemaMode !== SchemaDefinition.CODE ) {
-      throw new Error('API cannot append to schema because schema definition mode is not configured as CODE.');
-    }
-    const sep = delimiter ?? '';
-    this.schema.definition = `${this.schema.definition}${sep}${addition}\n`;
+  public addToSchema(addition: string, delimiter?: string): void {
+    this.schema.addToSchema(addition, delimiter);
   }
 
   /**
-   * Add an object type to the schema
+   * Add type to the schema
    *
-   * @param name the name of the object type
-   * @param props the definition
+   * @param type the intermediate type to add to the schema
    *
    * @experimental
    */
-  public addType(name: string, props: ObjectTypeProps): ObjectType {
-    if ( this.schemaMode !== SchemaDefinition.CODE ) {
-      throw new Error('API cannot add type because schema definition mode is not configured as CODE.');
-    };
-    const type = new ObjectType(name, {
-      definition: props.definition,
-      directives: props.directives,
-    });
-    this.appendToSchema(type.toString());
-    return type;
+  public addType(type: IIntermediateType): IIntermediateType {
+    return this.schema.addType(type);
   }
 }

packages/@aws-cdk/aws-appsync/lib/index.ts

@@ -4,6 +4,7 @@ export * from './key';
 export * from './data-source';
 export * from './mapping-template';
 export * from './resolver';
+export * from './schema';
 export * from './schema-intermediate';
 export * from './schema-field';
 export * from './schema-base';

packages/@aws-cdk/aws-appsync/lib/private.ts

@@ -4,6 +4,14 @@ function concatAndDedup<T>(left: T[], right: T[]): T[] {
   });
 }
 
+/**
+ * Utility enum for Schema class
+ */
+export enum SchemaMode {
+  FILE = 'FILE',
+  CODE = 'CODE',
+};
+
 /**
  * Utility class to represent DynamoDB key conditions.
  */

packages/@aws-cdk/aws-appsync/lib/schema-base.ts

@@ -1,5 +1,5 @@
 import { Resolver } from './resolver';
-import { ResolvableFieldOptions } from './schema-field';
+import { ResolvableFieldOptions, BaseTypeOptions, GraphqlType } from './schema-field';
 import { InterfaceType } from './schema-intermediate';
 
 /**
@@ -105,6 +105,16 @@ export interface IIntermediateType {
    */
   readonly intermediateType?: InterfaceType;
 
+  /**
+   * Create an GraphQL Type representing this Intermediate Type
+   *
+   * @param options the options to configure this attribute
+   * - isList
+   * - isRequired
+   * - isRequiredList
+   */
+  attribute(options?: BaseTypeOptions): GraphqlType;
+
   /**
    * Generate the string of this object type
    */