feat(appsync): code-first schema allows for object type definition

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

@@ -60,7 +60,7 @@ const api = new appsync.GraphQLApi(stack, 'Api', {
 const demoTable = new db.Table(stack, 'DemoTable', {
   partitionKey: {
     name: 'id',
-    type: AttributeType.STRING,
+    type: db.AttributeType.STRING,
   },
 });
 
@@ -161,3 +161,187 @@ api.grantMutation(role, 'updateExample');
 // For custom types and granular design
 api.grant(role, appsync.IamResource.ofType('Mutation', 'updateExample'), 'appsync:GraphQL');
 ```
+
+### Code-First Schema
+
+CDK offers the ability to generate your schema in a code-first approach. 
+A code-first approach offers a developer workflow with:
+- **modularity**: organizing schema type definitions into different files
+- **reusability**: simplifying down boilerplate/repetitive code
+- **consistency**: resolvers and schema definition will always be synced
+
+The code-first approach allows for dynamic schema generation. You can generate your schema based on variables and templates to reduce code duplication.
+
+#### Code-First Example
+
+We are going to reference the [example](#Example) through a code-first approach.
+
+```ts
+import * as appsync from '@aws-cdk/aws-appsync';
+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'),
+  authorizationConfig: {
+    defaultAuthorization: {
+      authorizationType: appsync.AuthorizationType.IAM
+    },
+  },
+});
+
+const demoTable = new db.Table(stack, 'DemoTable', {
+  partitionKey: {
+    name: 'id',
+    type: db.AttributeType.STRING,
+  },
+});
+
+const demoDS = api.addDynamoDbDataSource('demoDataSource', 'Table for Demos', demoTable);
+
+// Schema Definition starts here
+
+const demo = api.addType('demo', {
+  definition: {
+    id: appsync.GraphqlType.string({ isRequired: true }),
+    version: appsync.GraphqlType.string({ isRequired: true }),
+  },
+});
+
+```
+
+#### GraphQL Types
+
+One of the benefits of GraphQL is its strongly typed nature. We define the 
+types within an object, query, mutation, interface, etc. as **GraphQL Types**. 
+
+GraphQL Types are the building blocks of types, whether they are scalar, objects, 
+interfaces, etc. GraphQL Types can be:
+- [**Scalar Types**](https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html): Id, Int, String, AWSDate, etc. 
+- **Object Types**: types that you generate (i.e. `demo` from the example above)
+- **Interface Types**: abstract types that define the base implementation of other 
+Intermediate Types
+
+More concretely, GraphQL Types are simply the types appended to variables. 
+Referencing the object type `Demo` in the previous example, the GraphQL Types 
+is `String!` and is applied to both the names `id` and `version`.
+
+#### Intermediate Types
+
+Intermediate Types are abstractions above Scalar Types. They have a set of defined 
+fields, where each field corresponds to another type in the system. Intermediate 
+Types will be the meat of your GraphQL Schema as they are the types defined by you.
+
+Intermediate Types include:
+- [**Interface Types**](#Interface-Types)
+- [**Object Types**](#Object-Types)
+
+#### Interface Types
+
+**Interface Types** are abstract types that define the implementation of other
+intermediate types. They are useful for eliminating duplication and can be used
+to generate Object Types with less work.
+
+You can create Interface Types in two ways:
+
+1. Interface Types can be created ***externally***.
+    ```ts
+    const node = new appsync.InterfaceType('Node', {
+      definition: {
+        id: appsync.GraphqlType.string({ isRequired: true }),
+      },
+    });
+    ```
+2. Interface Types can be created ***externally*** from another Interface Type.
+    ```ts
+    const node = new appsync.InterfaceType('Node', {
+      definition: {
+        id: appsync.GraphqlType.string({ isRequired: true }),
+      },
+    });
+    const superNode = new appsync.InterfaceType.extendInterface('SuperNode', node, {
+      definition: {
+        speicalId: appsync.GraphqlType.string(),
+      },
+    });
+    ```
+
+#### Object Types
+
+**Object Types** are types that you declare. For example, in the [code-first example](#code-first-example)
+the `demo` variable is an **Object Type**. **Object Types** are defined by 
+GraphQL Types and are only usable when linked to a GraphQL Api.
+
+You can create Object Types in three ways:
+
+1. Object Types can be created ***externally***.
+    ```ts
+    const api = new appsync.GraphQLApi(stack, 'Api', {
+      name: 'demo',
+      schemaDefinition: appsync.SchemaDefinition.CODE,
+    });
+    const demo = new appsync.ObjectType('Demo', {
+      defintion: {
+        id: appsync.GraphqlType.string({ isRequired: true }),
+        version: appsync.GraphqlType.string({ isRequired: true }),
+      },
+    });
+
+    api.appendToSchema(object.toString());
+    ```
+    > This method allows for reusability and modularity, ideal for larger projects. 
+    For example, imagine moving all Object Type definition outside the stack.
+
+    `scalar-types.ts` - a file for scalar type definitions
+    ```ts
+    export const required_string = new appsync.GraphqlType.string({ isRequired: true });
+    ```
+
+    `object-types.ts` - a file for object type definitions
+    ```ts
+    import { required_string } from './scalar-types';
+    export const demo = new appsync.ObjectType('Demo', {
+      defintion: {
+        id: required_string,
+        version: required_string,
+      },
+    });
+    ```
+
+    `cdk-stack.ts` - a file containing our cdk stack
+    ```ts
+    import { demo } from './object-types';
+    api.appendToSchema(demo.toString());
+    ```
+
+2. Object Types can be created ***externally*** from an Interface Type.
+    ```ts
+    const node = new appsync.InterfaceType('Node', {
+      definition: {
+        id: appsync.GraphqlType.string({ isRequired: true }),
+      },
+    });
+    const demo = new appsync.ObjectType.implementInterface('Demo', node, {
+      defintion: {
+        version: appsync.GraphqlType.string({ isRequired: true }),
+      },
+    });
+    ```
+    > This method allows for reusability and modularity, ideal for reducing code duplication. 
+
+3. Object Types can be created ***internally*** within the GraphQL API.
+    ```ts
+    const api = new appsync.GraphQLApi(stack, 'Api', {
+      name: 'demo',
+      schemaDefinition: appsync.SchemaDefinition.CODE,
+    });
+    api.addType('Demo', {
+      defintion: {
+        id: appsync.GraphqlType.string({ isRequired: true }),
+        version: appsync.GraphqlType.string({ isRequired: true }),
+      },
+    });
+    ```
+    > This method provides easy use and is ideal for smaller projects.
+

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

@@ -6,6 +6,7 @@ import { IFunction } from '@aws-cdk/aws-lambda';
 import { Construct, Duration, IResolvable, Stack } from '@aws-cdk/core';
 import { CfnApiKey, CfnGraphQLApi, CfnGraphQLSchema } from './appsync.generated';
 import { DynamoDbDataSource, HttpDataSource, LambdaDataSource, NoneDataSource } from './data-source';
+import { ObjectType, ObjectTypeProps } from './schema-types';
 
 /**
  * enum with all possible values for AppSync authorization type
@@ -683,33 +684,20 @@ export class GraphQLApi extends Construct {
     return authModes ? this.formatAdditionalAuthorizationModes(authModes) : undefined;
   }
 
-  /**
-   * Sets schema defintiion to input if schema mode is configured with SchemaDefinition.CODE
-   *
-   * @param definition string that is the graphql representation of schema
-   * @experimental temporary
-   */
-  public updateDefinition (definition: string): void{
-    if ( this.schemaMode != SchemaDefinition.CODE ) {
-      throw new Error('API cannot add type because schema definition mode is not configured as CODE.');
-    }
-    this.schema.definition = definition;
-  }
-
   /**
    * 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) {
+    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 ) {
+    } else if ( this.schemaMode === SchemaDefinition.FILE && file ) {
       definition = readFileSync(file).toString('UTF-8');
-    } else if ( this.schemaMode == SchemaDefinition.CODE && !file ) {
+    } else if ( this.schemaMode === SchemaDefinition.CODE && !file ) {
       definition = '';
-    } else if ( this.schemaMode == SchemaDefinition.CODE && file) {
+    } 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');
     }
 
@@ -718,4 +706,42 @@ export class GraphQLApi extends Construct {
       definition,
     });
   }
+
+  /**
+   * Escape hatch to append to Schema as desired. Will always result
+   * in a newline.
+   *
+   * @param addition the addition to add to schema
+   * @param delimiter the delimiter between schema and addition
+   * @default - ''
+   *
+   * @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`;
+  }
+
+  /**
+   * Add an object type to the schema
+   *
+   * @param name the name of the object type
+   * @param props the definition
+   *
+   * @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;
+  }
 }

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

@@ -4,4 +4,5 @@ export * from './key';
 export * from './data-source';
 export * from './mapping-template';
 export * from './resolver';
+export * from './schema-types';
 export * from './graphqlapi';