[aws-appsync] code-first schema generation

Allow definition of the schema to happen within the cdk stack. The generated schema would be directly inserted into the CloudFormation Template at runtime.

Use Case

Currently there are only two ways to define schema: ,inline or with a file.

Inline

const inlineSchemaDefintion = `
  ...
`;
const api = new appsync.GraphQLApi(stack, 'api', {
  name: 'api',
  schemaDefinition: `${inlineSchemaDefinition}`,
});

File

const api = new appsync.GraphQLApi(stack, 'api', {
  name: 'api',
  schemaDefinitionFile: join(__dirname, 'schema.graphql'),
});

A code-first approach would allow for definition of the GraphQL schema to happen inline alongside resolvers.

Proposed Solution

Write the schema definition along with the resolvers inline.

Implementation

const api = new GraphQLApi(stack, 'ExampleApi', {
  name: 'example',
  schemaDefinition: SCHEMA.CODE,
  ...
}

const exampleTable = new db.Table(...);
const exampleDS = api.addDynamoDbDataSource('exampleDataSource', 'Table for Demos', exampleTable);

// NEW IMPLEMENTATION STARTS HERE

// Defining attribute types (i.e. Int! and String!)
const t_int_r = AttributeType.int().required();
const t_string_r = AttributeType.string().required();

// Defining Object Type ( i.e. type Example @aws_iam { id: Int! content: String! } )
const example = api.addType('Example', {
  definition: {
    id: t_int_r,
    content: t_string_r, 
  },
  directives: Directives.iam(),
});

// Defining the attribute type for the Object Type 'Example'
const t_example = AttributeType.object(t_example);
const t_example_l = AttributeType.object(t_example).list();

api.addQuery( 'getExamples', {
  type: t_example_l,
  resolve: [{
    dataSource: exampleDS,
    request: MappingTemplate.dynamoDbScanTable(),
    response: MappingTemplate.dynamoDbResultList(),
  }],
});

api.addMutation( 'addExample', {
  type: t_example,
  args: {
    version: t_string_r,
  },
  resolve: [{
    dataSource: exampleDS,
    request: MappingTemplate.dynamoDbPutItem(PrimaryKey.partition('id').auto(), Values.projecting('example')),
    response: MappingTemplate.dynamoDbResultItem(),
  }],
  directives: Directives.iam(),
});

Other

I will be using this issue as a way to track the smaller components of this feature request and as a point of discussion for implementation.

Visit this repository to see how to generate SWAPI in a code-first approach.

Features

• in memory schema generation (pr: #9283)
• code-first generation of object types (issue: #9307 pr: #9417)
• code-first generation of queries (issue: #9308 pr: #9992)
• code-first generation of mutations (issue: #9310 pr: #9992)
• code-first generation of subscriptions (issue: #9345 pr: #10078)
• code-first generation of interfaces (pr: #9417)
• code-first generation of enum (pr: #10023)
• code-first generation of inputs (pr: #10024)
• code-first generation of unions (pr: #10025)
• directives (pr: #9879)

---

This is a 🚀 Feature Request

[ranguard]

I’ve been doing a bit more reading and I think what I’m actually after is schema-stitching, or taking that further GraphQL federation support in AppSync would be even better - such that each service can be responsible for it’s own content in a shared schema and then be stitched together by a gateway. Some mention of it in aws/aws-appsync-community but no timeline.

With graphql-transform-federation it seems to be possible to hack something together now but an officially supported mechanism would go a long way.

As my end points aren’t public yet feels like might be worth running multiple GraphAPI end points for now and waiting for AppSync to catch up.

[asterikx]

Ooo I see now. I think there still are work arounds for this even with the code-first approach. For example, I believe to start, you could just have an empty schema.graphql file for BucketDeployment

That would solve the bootstrapping issue.

You could even make two stacks and have the BucketDeployment stack depend on the AppSync stack.

I think what you suggest is interleaving synth and build actions? I. e. first synth the stack that contains the AppSync API (which will output a schema.graphql, then generate the additional files from schema.graphql and build the frontend, and lastly synth the stack that contains the BucketDeplyoment for the frontend. Not sure if this is always possible, e.g. e.g. when using the new CDK pipeline construct where the stacks are grouped under a single stage.

Overall, these are really great points that we will keep in mind during implementation but seem out of scope for the use case of a code-first approach.

Yeah, it’s hard to foresee all scenarios. It is probably best to just try it out and tackle the issues as they arise. I think it’s important to keep developer experience in mind here.