# AWS AppSync Construct Library
<!--BEGIN STABILITY BANNER-->---
> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
> The APIs of higher level constructs in this module are experimental and under active development.
> They are subject to non-backward compatible changes or removal in any future version. These are
> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
> announced in the release notes. This means that while you may use them, you may need to update
> your source code when upgrading to a newer version of this package.
---
<!--END STABILITY BANNER-->
The `@aws-cdk/aws-appsync` package contains constructs for building flexible
APIs that use GraphQL.
```python
import aws_cdk.aws_appsync as appsync
```
## Example
### DynamoDB
Example of a GraphQL API with `AWS_IAM` [authorization](#authorization) resolving into a DynamoDb
backend data source.
GraphQL schema file `schema.graphql`:
```gql
type demo {
id: String!
version: String!
}
type Query {
getDemos: [ demo! ]
}
input DemoInput {
version: String!
}
type Mutation {
addDemo(input: DemoInput!): demo
}
```
CDK stack file `app-stack.ts`:
```python
api = appsync.GraphqlApi(self, "Api",
name="demo",
schema=appsync.Schema.from_asset(path.join(__dirname, "schema.graphql")),
authorization_config=appsync.AuthorizationConfig(
default_authorization=appsync.AuthorizationMode(
authorization_type=appsync.AuthorizationType.IAM
)
),
xray_enabled=True
)
demo_table = dynamodb.Table(self, "DemoTable",
partition_key=dynamodb.Attribute(
name="id",
type=dynamodb.AttributeType.STRING
)
)
demo_dS = api.add_dynamo_db_data_source("demoDataSource", demo_table)
# Resolver for the Query "getDemos" that scans the DynamoDb table and returns the entire list.
demo_dS.create_resolver(
type_name="Query",
field_name="getDemos",
request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(),
response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list()
)
# Resolver for the Mutation "addDemo" that puts the item into the DynamoDb table.
demo_dS.create_resolver(
type_name="Mutation",
field_name="addDemo",
request_mapping_template=appsync.MappingTemplate.dynamo_db_put_item(
appsync.PrimaryKey.partition("id").auto(),
appsync.Values.projecting("input")),
response_mapping_template=appsync.MappingTemplate.dynamo_db_result_item()
)
```
### Aurora Serverless
AppSync provides a data source for executing SQL commands against Amazon Aurora
Serverless clusters. You can use AppSync resolvers to execute SQL statements
against the Data API with GraphQL queries, mutations, and subscriptions.
```python
# Build a data source for AppSync to access the database.
# api: appsync.GraphqlApi
# Create username and password secret for DB Cluster
secret = rds.DatabaseSecret(self, "AuroraSecret",
username="clusteradmin"
)
# The VPC to place the cluster in
vpc = ec2.Vpc(self, "AuroraVpc")
# Create the serverless cluster, provide all values needed to customise the database.
cluster = rds.ServerlessCluster(self, "AuroraCluster",
engine=rds.DatabaseClusterEngine.AURORA_MYSQL,
vpc=vpc,
credentials={"username": "clusteradmin"},
cluster_identifier="db-endpoint-test",
default_database_name="demos"
)
rds_dS = api.add_rds_data_source("rds", cluster, secret, "demos")
# Set up a resolver for an RDS query.
rds_dS.create_resolver(
type_name="Query",
field_name="getDemosRds",
request_mapping_template=appsync.MappingTemplate.from_string("""
{
"version": "2018-05-29",
"statements": [
"SELECT * FROM demos"
]
}
"""),
response_mapping_template=appsync.MappingTemplate.from_string("""
$utils.toJson($utils.rds.toJsonObject($ctx.result)[0])
""")
)
# Set up a resolver for an RDS mutation.
rds_dS.create_resolver(
type_name="Mutation",
field_name="addDemoRds",
request_mapping_template=appsync.MappingTemplate.from_string("""
{
"version": "2018-05-29",
"statements": [
"INSERT INTO demos VALUES (:id, :version)",
"SELECT * WHERE id = :id"
],
"variableMap": {
":id": $util.toJson($util.autoId()),
":version": $util.toJson($ctx.args.version)
}
}
"""),
response_mapping_template=appsync.MappingTemplate.from_string("""
$utils.toJson($utils.rds.toJsonObject($ctx.result)[1][0])
""")
)
```
### HTTP Endpoints
GraphQL schema file `schema.graphql`:
```gql
type job {
id: String!
version: String!
}
input DemoInput {
version: String!
}
type Mutation {
callStepFunction(input: DemoInput!): job
}
```
GraphQL request mapping template `request.vtl`:
```json
{
"version": "2018-05-29",
"method": "POST",
"resourcePath": "/",
"params": {
"headers": {
"content-type": "application/x-amz-json-1.0",
"x-amz-target":"AWSStepFunctions.StartExecution"
},
"body": {
"stateMachineArn": "<your step functions arn>",
"input": "{ \"id\": \"$context.arguments.id\" }"
}
}
}
```
GraphQL response mapping template `response.vtl`:
```json
{
"id": "${context.result.id}"
}
```
CDK stack file `app-stack.ts`:
```python
api = appsync.GraphqlApi(self, "api",
name="api",
schema=appsync.Schema.from_asset(path.join(__dirname, "schema.graphql"))
)
http_ds = api.add_http_data_source("ds", "https://states.amazonaws.com",
name="httpDsWithStepF",
description="from appsync to StepFunctions Workflow",
authorization_config=appsync.AwsIamConfig(
signing_region="us-east-1",
signing_service_name="states"
)
)
http_ds.create_resolver(
type_name="Mutation",
field_name="callStepFunction",
request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"),
response_mapping_template=appsync.MappingTemplate.from_file("response.vtl")
)
```
### Amazon OpenSearch Service
AppSync has builtin support for Amazon OpenSearch Service (successor to Amazon
Elasticsearch Service) from domains that are provisioned through your AWS account. You can
use AppSync resolvers to perform GraphQL operations such as queries, mutations, and
subscriptions.
```python
import aws_cdk.aws_opensearchservice as opensearch
# api: appsync.GraphqlApi
user = iam.User(self, "User")
domain = opensearch.Domain(self, "Domain",
version=opensearch.EngineVersion.OPENSEARCH_1_2,
removal_policy=RemovalPolicy.DESTROY,
fine_grained_access_control=opensearch.AdvancedSecurityOptions(master_user_arn=user.user_arn),
encryption_at_rest=opensearch.EncryptionAtRestOptions(enabled=True),
node_to_node_encryption=True,
enforce_https=True
)
ds = api.add_open_search_data_source("ds", domain)
ds.create_resolver(
type_name="Query",
field_name="getTests",
request_mapping_template=appsync.MappingTemplate.from_string(JSON.stringify({
"version": "2017-02-28",
"operation": "GET",
"path": "/id/post/_search",
"params": {
"headers": {},
"query_string": {},
"body": {"from": 0, "size": 50}
}
})),
response_mapping_template=appsync.MappingTemplate.from_string("""[
#foreach($entry in $context.result.hits.hits)
#if( $velocityCount > 1 ) , #end
$utils.toJson($entry.get("_source"))
#end
]""")
)
```
## Custom Domain Names
For many use cases you may want to associate a custom domain name with your
GraphQL API. This can be done during the API creation.
```python
import aws_cdk.aws_certificatemanager as acm
import aws_cdk.aws_route53 as route53
# hosted zone and route53 features
# hosted_zone_id: str
zone_name = "example.com"
my_domain_name = "api.example.com"
certificate = acm.Certificate(self, "cert", domain_name=my_domain_name)
api = appsync.GraphqlApi(self, "api",
name="myApi",
domain_name=appsync.DomainOptions(
certificate=certificate,
domain_name=my_domain_name
)
)
# hosted zone for adding appsync domain
zone = route53.HostedZone.from_hosted_zone_attributes(self, "HostedZone",
hosted_zone_id=hosted_zone_id,
zone_name=zone_name
)
# create a cname to the appsync domain. will map to something like xxxx.cloudfront.net
route53.CnameRecord(self, "CnameApiRecord",
record_name="api",
zone=zone,
domain_name=my_domain_name
)
```
## 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.
```python
api = appsync.GraphqlApi(self, "api", name="myApi")
```
CDK will declare a `Schema` class that will give your Api access functions to
define your schema code-first: `addType`, `addToSchema`, etc.
You can also declare your `Schema` class outside of your CDK stack, to define
your schema externally.
```python
schema = appsync.Schema()
schema.add_type(appsync.ObjectType("demo",
definition={"id": appsync.GraphqlType.id()}
))
api = appsync.GraphqlApi(self, "api",
name="myApi",
schema=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.
```python
api = appsync.GraphqlApi(self, "api",
name="myApi",
schema=appsync.Schema.from_asset(path.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
the ability to add data sources and resolvers through a `IGraphqlApi` interface.
```python
# api: appsync.GraphqlApi
# table: dynamodb.Table
imported_api = appsync.GraphqlApi.from_graphql_api_attributes(self, "IApi",
graphql_api_id=api.api_id,
graphql_api_arn=api.arn
)
imported_api.add_dynamo_db_data_source("TableDataSource", table)
```
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.
## Authorization
There are multiple authorization types available for GraphQL API to cater to different
access use cases. They are:
* API Keys (`AuthorizationType.API_KEY`)
* Amazon Cognito User Pools (`AuthorizationType.USER_POOL`)
* OpenID Connect (`AuthorizationType.OPENID_CONNECT`)
* AWS Identity and Access Management (`AuthorizationType.AWS_IAM`)
* AWS Lambda (`AuthorizationType.AWS_LAMBDA`)
These types can be used simultaneously in a single API, allowing different types of clients to
access data. When you specify an authorization type, you can also specify the corresponding
authorization mode to finish defining your authorization. For example, this is a GraphQL API
with AWS Lambda Authorization.
```python
import aws_cdk.aws_lambda as lambda_
# auth_function: lambda.Function
appsync.GraphqlApi(self, "api",
name="api",
schema=appsync.Schema.from_asset(path.join(__dirname, "appsync.test.graphql")),
authorization_config=appsync.AuthorizationConfig(
default_authorization=appsync.AuthorizationMode(
authorization_type=appsync.AuthorizationType.LAMBDA,
lambda_authorizer_config=appsync.LambdaAuthorizerConfig(
handler=auth_function
)
)
)
)
```
## 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.
When configuring permissions, you can specify specific resources to only be
accessible by `IAM` authorization. For example, if you want to only allow mutability
for `IAM` authorized access you would configure the following.
In `schema.graphql`:
```gql
type Mutation {
updateExample(...): ...
@aws_iam
}
```
In `IAM`:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"appsync:GraphQL"
],
"Resource": [
"arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample"
]
}
]
}
```
See [documentation](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) for more details.
To make this easier, CDK provides `grant` API.
Use the `grant` function for more granular authorization.
```python
# api: appsync.GraphqlApi
role = iam.Role(self, "Role",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
)
api.grant(role, appsync.IamResource.custom("types/Mutation/fields/updateExample"), "appsync:GraphQL")
```
### IamResource
In order to use the `grant` functions, you need to use the class `IamResource`.
* `IamResource.custom(...arns)` permits custom ARNs and requires an argument.
* `IamResouce.ofType(type, ...fields)` permits ARNs for types and their fields.
* `IamResource.all()` permits ALL resources.
### Generic Permissions
Alternatively, you can use more generic `grant` functions to accomplish the same usage.
These include:
* grantMutation (use to grant access to Mutation fields)
* grantQuery (use to grant access to Query fields)
* grantSubscription (use to grant access to Subscription fields)
```python
# api: appsync.GraphqlApi
# role: iam.Role
# For generic types
api.grant_mutation(role, "updateExample")
# For custom types and granular design
api.grant(role, appsync.IamResource.of_type("Mutation", "updateExample"), "appsync:GraphQL")
```
## Pipeline Resolvers and AppSync Functions
AppSync Functions are local functions that perform certain operations onto a
backend data source. Developers can compose operations (Functions) and execute
them in sequence with Pipeline Resolvers.
```python
# api: appsync.GraphqlApi
appsync_function = appsync.AppsyncFunction(self, "function",
name="appsync_function",
api=api,
data_source=api.add_none_data_source("none"),
request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"),
response_mapping_template=appsync.MappingTemplate.from_file("response.vtl")
)
```
AppSync Functions are used in tandem with pipeline resolvers to compose multiple
operations.
```python
# api: appsync.GraphqlApi
# appsync_function: appsync.AppsyncFunction
pipeline_resolver = appsync.Resolver(self, "pipeline",
api=api,
data_source=api.add_none_data_source("none"),
type_name="typeName",
field_name="fieldName",
request_mapping_template=appsync.MappingTemplate.from_file("beforeRequest.vtl"),
pipeline_config=[appsync_function],
response_mapping_template=appsync.MappingTemplate.from_file("afterResponse.vtl")
)
```
Learn more about Pipeline Resolvers and AppSync Functions [here](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html).
## 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
To showcase the code-first approach. Let's try to model the following schema segment.
```gql
interface Node {
id: String
}
type Query {
allFilms(after: String, first: Int, before: String, last: Int): FilmConnection
}
type FilmNode implements Node {
filmName: String
}
type FilmConnection {
edges: [FilmEdge]
films: [Film]
totalCount: Int
}
type FilmEdge {
node: Film
cursor: String
}
```
Above we see a schema that allows for generating paginated responses. For example,
we can query `allFilms(first: 100)` since `FilmConnection` acts as an intermediary
for holding `FilmEdges` we can write a resolver to return the first 100 films.
In a separate file, we can declare our object types and related functions.
We will call this file `object-types.ts` and we will have created it in a way that
allows us to generate other `XxxConnection` and `XxxEdges` in the future.
```python
import aws_cdk.aws_appsync as appsync
pluralize = require("pluralize")
args = {
"after": appsync.GraphqlType.string(),
"first": appsync.GraphqlType.int(),
"before": appsync.GraphqlType.string(),
"last": appsync.GraphqlType.int()
}
Node = appsync.InterfaceType("Node",
definition={"id": appsync.GraphqlType.string()}
)
FilmNode = appsync.ObjectType("FilmNode",
interface_types=[Node],
definition={"film_name": appsync.GraphqlType.string()}
)
def generate_edge_and_connection(base):
edge = appsync.ObjectType(f"{base.name}Edge",
definition={"node": base.attribute(), "cursor": appsync.GraphqlType.string()}
)
connection = appsync.ObjectType(f"{base.name}Connection",
definition={
"edges": edge.attribute(is_list=True),
"pluralize(base.name)": base.attribute(is_list=True),
"total_count": appsync.GraphqlType.int()
}
)
return {"edge": edge, "connection": connection}
```
Finally, we will go to our `cdk-stack` and combine everything together
to generate our schema.
```python
# dummy_request: appsync.MappingTemplate
# dummy_response: appsync.MappingTemplate
api = appsync.GraphqlApi(self, "Api",
name="demo"
)
object_types = [Node, FilmNode]
film_connections = generate_edge_and_connection(FilmNode)
api.add_query("allFilms", appsync.ResolvableField(
return_type=film_connections.connection.attribute(),
args=args,
data_source=api.add_none_data_source("none"),
request_mapping_template=dummy_request,
response_mapping_template=dummy_response
))
api.add_type(Node)
api.add_type(FilmNode)
api.add_type(film_connections.edge)
api.add_type(film_connections.connection)
```
Notice how we can utilize the `generateEdgeAndConnection` function to generate
Object Types. In the future, if we wanted to create more Object Types, we can simply
create the base Object Type (i.e. Film) and from there we can generate its respective
`Connections` and `Edges`.
Check out a more in-depth example [here](https://github.com/BryanPan342/starwars-code-first).
## 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**](#Object-Types): types that you generate (i.e. `demo` from the example above)
* [**Interface Types**](#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`.
### Directives
`Directives` are attached to a field or type and affect the execution of queries,
mutations, and types. With AppSync, we use `Directives` to configure authorization.
CDK provides static functions to add directives to your Schema.
* `Directive.iam()` sets a type or field's authorization to be validated through `Iam`
* `Directive.apiKey()` sets a type or field's authorization to be validated through a `Api Key`
* `Directive.oidc()` sets a type or field's authorization to be validated through `OpenID Connect`
* `Directive.cognito(...groups: string[])` sets a type or field's authorization to be validated
through `Cognito User Pools`
* `groups` the name of the cognito groups to give access
To learn more about authorization and directives, read these docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/security.html).
### Field and Resolvable Fields
While `GraphqlType` is a base implementation for GraphQL fields, we have abstractions
on top of `GraphqlType` that provide finer grain support.
### Field
`Field` extends `GraphqlType` and will allow you to define arguments. [**Interface Types**](#Interface-Types) are not resolvable and this class will allow you to define arguments,
but not its resolvers.
For example, if we want to create the following type:
```gql
type Node {
test(argument: string): String
}
```
The CDK code required would be:
```python
field = appsync.Field(
return_type=appsync.GraphqlType.string(),
args={
"argument": appsync.GraphqlType.string()
}
)
type = appsync.InterfaceType("Node",
definition={"test": field}
)
```
### Resolvable Fields
`ResolvableField` extends `Field` and will allow you to define arguments and its resolvers.
[**Object Types**](#Object-Types) can have fields that resolve and perform operations on
your backend.
You can also create resolvable fields for object types.
```gql
type Info {
node(id: String): String
}
```
The CDK code required would be:
```python
# api: appsync.GraphqlApi
# dummy_request: appsync.MappingTemplate
# dummy_response: appsync.MappingTemplate
info = appsync.ObjectType("Info",
definition={
"node": appsync.ResolvableField(
return_type=appsync.GraphqlType.string(),
args={
"id": appsync.GraphqlType.string()
},
data_source=api.add_none_data_source("none"),
request_mapping_template=dummy_request,
response_mapping_template=dummy_response
)
}
)
```
To nest resolvers, we can also create top level query types that call upon
other types. Building off the previous example, if we want the following graphql
type definition:
```gql
type Query {
get(argument: string): Info
}
```
The CDK code required would be:
```python
# api: appsync.GraphqlApi
# dummy_request: appsync.MappingTemplate
# dummy_response: appsync.MappingTemplate
query = appsync.ObjectType("Query",
definition={
"get": appsync.ResolvableField(
return_type=appsync.GraphqlType.string(),
args={
"argument": appsync.GraphqlType.string()
},
data_source=api.add_none_data_source("none"),
request_mapping_template=dummy_request,
response_mapping_template=dummy_response
)
}
)
```
Learn more about fields and resolvers [here](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html).
### Intermediate Types
Intermediate Types are defined by Graphql Types and Fields. 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)
* [**Enum Types**](#Enum-Types)
* [**Input Types**](#Input-Types)
* [**Union Types**](#Union-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 ***externally***.
```python
node = appsync.InterfaceType("Node",
definition={
"id": appsync.GraphqlType.string(is_required=True)
}
)
```
To learn more about **Interface Types**, read the docs [here](https://graphql.org/learn/schema/#interfaces).
#### 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 two ways:
1. Object Types can be created ***externally***.
```python
api = appsync.GraphqlApi(self, "Api",
name="demo"
)
demo = appsync.ObjectType("Demo",
definition={
"id": appsync.GraphqlType.string(is_required=True),
"version": appsync.GraphqlType.string(is_required=True)
}
)
api.add_type(demo)
```
> This method allows for reusability and modularity, ideal for larger projects.
> For example, imagine moving all Object Type definition outside the stack.
`object-types.ts` - a file for object type definitions
```python
import aws_cdk.aws_appsync as appsync
demo = appsync.ObjectType("Demo",
definition={
"id": appsync.GraphqlType.string(is_required=True),
"version": appsync.GraphqlType.string(is_required=True)
}
)
```
`cdk-stack.ts` - a file containing our cdk stack
```python
# api: appsync.GraphqlApi
api.add_type(demo)
```
2. Object Types can be created ***externally*** from an Interface Type.
```python
node = appsync.InterfaceType("Node",
definition={
"id": appsync.GraphqlType.string(is_required=True)
}
)
demo = appsync.ObjectType("Demo",
interface_types=[node],
definition={
"version": appsync.GraphqlType.string(is_required=True)
}
)
```
> This method allows for reusability and modularity, ideal for reducing code duplication.
To learn more about **Object Types**, read the docs [here](https://graphql.org/learn/schema/#object-types-and-fields).
#### Enum Types
**Enum Types** are a special type of Intermediate Type. They restrict a particular
set of allowed values for other Intermediate Types.
```gql
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
```
> This means that wherever we use the type Episode in our schema, we expect it to
> be exactly one of NEWHOPE, EMPIRE, or JEDI.
The above GraphQL Enumeration Type can be expressed in CDK as the following:
```python
# api: appsync.GraphqlApi
episode = appsync.EnumType("Episode",
definition=["NEWHOPE", "EMPIRE", "JEDI"
]
)
api.add_type(episode)
```
To learn more about **Enum Types**, read the docs [here](https://graphql.org/learn/schema/#enumeration-types).
#### Input Types
**Input Types** are special types of Intermediate Types. They give users an
easy way to pass complex objects for top level Mutation and Queries.
```gql
input Review {
stars: Int!
commentary: String
}
```
The above GraphQL Input Type can be expressed in CDK as the following:
```python
# api: appsync.GraphqlApi
review = appsync.InputType("Review",
definition={
"stars": appsync.GraphqlType.int(is_required=True),
"commentary": appsync.GraphqlType.string()
}
)
api.add_type(review)
```
To learn more about **Input Types**, read the docs [here](https://graphql.org/learn/schema/#input-types).
#### Union Types
**Union Types** are a special type of Intermediate Type. They are similar to
Interface Types, but they cannot specify any common fields between types.
**Note:** the fields of a union type need to be `Object Types`. In other words, you
can't create a union type out of interfaces, other unions, or inputs.
```gql
union Search = Human | Droid | Starship
```
The above GraphQL Union Type encompasses the Object Types of Human, Droid and Starship. It
can be expressed in CDK as the following:
```python
# api: appsync.GraphqlApi
string = appsync.GraphqlType.string()
human = appsync.ObjectType("Human", definition={"name": string})
droid = appsync.ObjectType("Droid", definition={"name": string})
starship = appsync.ObjectType("Starship", definition={"name": string})
search = appsync.UnionType("Search",
definition=[human, droid, starship]
)
api.add_type(search)
```
To learn more about **Union Types**, read the docs [here](https://graphql.org/learn/schema/#union-types).
### Query
Every schema requires a top level Query type. By default, the schema will look
for the `Object Type` named `Query`. The top level `Query` is the **only** exposed
type that users can access to perform `GET` operations on your Api.
To add fields for these queries, we can simply run the `addQuery` function to add
to the schema's `Query` type.
```python
# api: appsync.GraphqlApi
# film_connection: appsync.InterfaceType
# dummy_request: appsync.MappingTemplate
# dummy_response: appsync.MappingTemplate
string = appsync.GraphqlType.string()
int = appsync.GraphqlType.int()
api.add_query("allFilms", appsync.ResolvableField(
return_type=film_connection.attribute(),
args={"after": string, "first": int, "before": string, "last": int},
data_source=api.add_none_data_source("none"),
request_mapping_template=dummy_request,
response_mapping_template=dummy_response
))
```
To learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-overview.html).
### Mutation
Every schema **can** have a top level Mutation type. By default, the schema will look
for the `ObjectType` named `Mutation`. The top level `Mutation` Type is the only exposed
type that users can access to perform `mutable` operations on your Api.
To add fields for these mutations, we can simply run the `addMutation` function to add
to the schema's `Mutation` type.
```python
# api: appsync.GraphqlApi
# film_node: appsync.ObjectType
# dummy_request: appsync.MappingTemplate
# dummy_response: appsync.MappingTemplate
string = appsync.GraphqlType.string()
int = appsync.GraphqlType.int()
api.add_mutation("addFilm", appsync.ResolvableField(
return_type=film_node.attribute(),
args={"name": string, "film_number": int},
data_source=api.add_none_data_source("none"),
request_mapping_template=dummy_request,
response_mapping_template=dummy_response
))
```
To learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-overview.html).
### Subscription
Every schema **can** have a top level Subscription type. The top level `Subscription` Type
is the only exposed type that users can access to invoke a response to a mutation. `Subscriptions`
notify users when a mutation specific mutation is called. This means you can make any data source
real time by specify a GraphQL Schema directive on a mutation.
**Note**: The AWS AppSync client SDK automatically handles subscription connection management.
To add fields for these subscriptions, we can simply run the `addSubscription` function to add
to the schema's `Subscription` type.
```python
# api: appsync.GraphqlApi
# film: appsync.InterfaceType
api.add_subscription("addedFilm", appsync.Field(
return_type=film.attribute(),
args={"id": appsync.GraphqlType.id(is_required=True)},
directives=[appsync.Directive.subscribe("addFilm")]
))
```
To learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/real-time-data.html).
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-appsync",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/15/8e/f1dd14fe4de9ff97073e9332ffa36629a335739d142a34a056b2c4e0bb7f/aws-cdk.aws-appsync-1.203.0.tar.gz",
"platform": null,
"description": "# AWS AppSync Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.\n\n\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n<!--END STABILITY BANNER-->\n\nThe `@aws-cdk/aws-appsync` package contains constructs for building flexible\nAPIs that use GraphQL.\n\n```python\nimport aws_cdk.aws_appsync as appsync\n```\n\n## Example\n\n### DynamoDB\n\nExample of a GraphQL API with `AWS_IAM` [authorization](#authorization) resolving into a DynamoDb\nbackend data source.\n\nGraphQL schema file `schema.graphql`:\n\n```gql\ntype demo {\n id: String!\n version: String!\n}\ntype Query {\n getDemos: [ demo! ]\n}\ninput DemoInput {\n version: String!\n}\ntype Mutation {\n addDemo(input: DemoInput!): demo\n}\n```\n\nCDK stack file `app-stack.ts`:\n\n```python\napi = appsync.GraphqlApi(self, \"Api\",\n name=\"demo\",\n schema=appsync.Schema.from_asset(path.join(__dirname, \"schema.graphql\")),\n authorization_config=appsync.AuthorizationConfig(\n default_authorization=appsync.AuthorizationMode(\n authorization_type=appsync.AuthorizationType.IAM\n )\n ),\n xray_enabled=True\n)\n\ndemo_table = dynamodb.Table(self, \"DemoTable\",\n partition_key=dynamodb.Attribute(\n name=\"id\",\n type=dynamodb.AttributeType.STRING\n )\n)\n\ndemo_dS = api.add_dynamo_db_data_source(\"demoDataSource\", demo_table)\n\n# Resolver for the Query \"getDemos\" that scans the DynamoDb table and returns the entire list.\ndemo_dS.create_resolver(\n type_name=\"Query\",\n field_name=\"getDemos\",\n request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(),\n response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list()\n)\n\n# Resolver for the Mutation \"addDemo\" that puts the item into the DynamoDb table.\ndemo_dS.create_resolver(\n type_name=\"Mutation\",\n field_name=\"addDemo\",\n request_mapping_template=appsync.MappingTemplate.dynamo_db_put_item(\n appsync.PrimaryKey.partition(\"id\").auto(),\n appsync.Values.projecting(\"input\")),\n response_mapping_template=appsync.MappingTemplate.dynamo_db_result_item()\n)\n```\n\n### Aurora Serverless\n\nAppSync provides a data source for executing SQL commands against Amazon Aurora\nServerless clusters. You can use AppSync resolvers to execute SQL statements\nagainst the Data API with GraphQL queries, mutations, and subscriptions.\n\n```python\n# Build a data source for AppSync to access the database.\n# api: appsync.GraphqlApi\n# Create username and password secret for DB Cluster\nsecret = rds.DatabaseSecret(self, \"AuroraSecret\",\n username=\"clusteradmin\"\n)\n\n# The VPC to place the cluster in\nvpc = ec2.Vpc(self, \"AuroraVpc\")\n\n# Create the serverless cluster, provide all values needed to customise the database.\ncluster = rds.ServerlessCluster(self, \"AuroraCluster\",\n engine=rds.DatabaseClusterEngine.AURORA_MYSQL,\n vpc=vpc,\n credentials={\"username\": \"clusteradmin\"},\n cluster_identifier=\"db-endpoint-test\",\n default_database_name=\"demos\"\n)\nrds_dS = api.add_rds_data_source(\"rds\", cluster, secret, \"demos\")\n\n# Set up a resolver for an RDS query.\nrds_dS.create_resolver(\n type_name=\"Query\",\n field_name=\"getDemosRds\",\n request_mapping_template=appsync.MappingTemplate.from_string(\"\"\"\n {\n \"version\": \"2018-05-29\",\n \"statements\": [\n \"SELECT * FROM demos\"\n ]\n }\n \"\"\"),\n response_mapping_template=appsync.MappingTemplate.from_string(\"\"\"\n $utils.toJson($utils.rds.toJsonObject($ctx.result)[0])\n \"\"\")\n)\n\n# Set up a resolver for an RDS mutation.\nrds_dS.create_resolver(\n type_name=\"Mutation\",\n field_name=\"addDemoRds\",\n request_mapping_template=appsync.MappingTemplate.from_string(\"\"\"\n {\n \"version\": \"2018-05-29\",\n \"statements\": [\n \"INSERT INTO demos VALUES (:id, :version)\",\n \"SELECT * WHERE id = :id\"\n ],\n \"variableMap\": {\n \":id\": $util.toJson($util.autoId()),\n \":version\": $util.toJson($ctx.args.version)\n }\n }\n \"\"\"),\n response_mapping_template=appsync.MappingTemplate.from_string(\"\"\"\n $utils.toJson($utils.rds.toJsonObject($ctx.result)[1][0])\n \"\"\")\n)\n```\n\n### HTTP Endpoints\n\nGraphQL schema file `schema.graphql`:\n\n```gql\ntype job {\n id: String!\n version: String!\n}\n\ninput DemoInput {\n version: String!\n}\n\ntype Mutation {\n callStepFunction(input: DemoInput!): job\n}\n```\n\nGraphQL request mapping template `request.vtl`:\n\n```json\n{\n \"version\": \"2018-05-29\",\n \"method\": \"POST\",\n \"resourcePath\": \"/\",\n \"params\": {\n \"headers\": {\n \"content-type\": \"application/x-amz-json-1.0\",\n \"x-amz-target\":\"AWSStepFunctions.StartExecution\"\n },\n \"body\": {\n \"stateMachineArn\": \"<your step functions arn>\",\n \"input\": \"{ \\\"id\\\": \\\"$context.arguments.id\\\" }\"\n }\n }\n}\n```\n\nGraphQL response mapping template `response.vtl`:\n\n```json\n{\n \"id\": \"${context.result.id}\"\n}\n```\n\nCDK stack file `app-stack.ts`:\n\n```python\napi = appsync.GraphqlApi(self, \"api\",\n name=\"api\",\n schema=appsync.Schema.from_asset(path.join(__dirname, \"schema.graphql\"))\n)\n\nhttp_ds = api.add_http_data_source(\"ds\", \"https://states.amazonaws.com\",\n name=\"httpDsWithStepF\",\n description=\"from appsync to StepFunctions Workflow\",\n authorization_config=appsync.AwsIamConfig(\n signing_region=\"us-east-1\",\n signing_service_name=\"states\"\n )\n)\n\nhttp_ds.create_resolver(\n type_name=\"Mutation\",\n field_name=\"callStepFunction\",\n request_mapping_template=appsync.MappingTemplate.from_file(\"request.vtl\"),\n response_mapping_template=appsync.MappingTemplate.from_file(\"response.vtl\")\n)\n```\n\n### Amazon OpenSearch Service\n\nAppSync has builtin support for Amazon OpenSearch Service (successor to Amazon\nElasticsearch Service) from domains that are provisioned through your AWS account. You can\nuse AppSync resolvers to perform GraphQL operations such as queries, mutations, and\nsubscriptions.\n\n```python\nimport aws_cdk.aws_opensearchservice as opensearch\n\n# api: appsync.GraphqlApi\n\n\nuser = iam.User(self, \"User\")\ndomain = opensearch.Domain(self, \"Domain\",\n version=opensearch.EngineVersion.OPENSEARCH_1_2,\n removal_policy=RemovalPolicy.DESTROY,\n fine_grained_access_control=opensearch.AdvancedSecurityOptions(master_user_arn=user.user_arn),\n encryption_at_rest=opensearch.EncryptionAtRestOptions(enabled=True),\n node_to_node_encryption=True,\n enforce_https=True\n)\nds = api.add_open_search_data_source(\"ds\", domain)\n\nds.create_resolver(\n type_name=\"Query\",\n field_name=\"getTests\",\n request_mapping_template=appsync.MappingTemplate.from_string(JSON.stringify({\n \"version\": \"2017-02-28\",\n \"operation\": \"GET\",\n \"path\": \"/id/post/_search\",\n \"params\": {\n \"headers\": {},\n \"query_string\": {},\n \"body\": {\"from\": 0, \"size\": 50}\n }\n })),\n response_mapping_template=appsync.MappingTemplate.from_string(\"\"\"[\n #foreach($entry in $context.result.hits.hits)\n #if( $velocityCount > 1 ) , #end\n $utils.toJson($entry.get(\"_source\"))\n #end\n ]\"\"\")\n)\n```\n\n## Custom Domain Names\n\nFor many use cases you may want to associate a custom domain name with your\nGraphQL API. This can be done during the API creation.\n\n```python\nimport aws_cdk.aws_certificatemanager as acm\nimport aws_cdk.aws_route53 as route53\n\n# hosted zone and route53 features\n# hosted_zone_id: str\nzone_name = \"example.com\"\n\n\nmy_domain_name = \"api.example.com\"\ncertificate = acm.Certificate(self, \"cert\", domain_name=my_domain_name)\napi = appsync.GraphqlApi(self, \"api\",\n name=\"myApi\",\n domain_name=appsync.DomainOptions(\n certificate=certificate,\n domain_name=my_domain_name\n )\n)\n\n# hosted zone for adding appsync domain\nzone = route53.HostedZone.from_hosted_zone_attributes(self, \"HostedZone\",\n hosted_zone_id=hosted_zone_id,\n zone_name=zone_name\n)\n\n# create a cname to the appsync domain. will map to something like xxxx.cloudfront.net\nroute53.CnameRecord(self, \"CnameApiRecord\",\n record_name=\"api\",\n zone=zone,\n domain_name=my_domain_name\n)\n```\n\n## Schema\n\nEvery GraphQL Api needs a schema to define the Api. CDK offers `appsync.Schema`\nfor static convenience methods for various types of schema declaration: code-first\nor schema-first.\n\n### Code-First\n\nWhen declaring your GraphQL Api, CDK defaults to a code-first approach if the\n`schema` property is not configured.\n\n```python\napi = appsync.GraphqlApi(self, \"api\", name=\"myApi\")\n```\n\nCDK will declare a `Schema` class that will give your Api access functions to\ndefine your schema code-first: `addType`, `addToSchema`, etc.\n\nYou can also declare your `Schema` class outside of your CDK stack, to define\nyour schema externally.\n\n```python\nschema = appsync.Schema()\nschema.add_type(appsync.ObjectType(\"demo\",\n definition={\"id\": appsync.GraphqlType.id()}\n))\napi = appsync.GraphqlApi(self, \"api\",\n name=\"myApi\",\n schema=schema\n)\n```\n\nSee the [code-first schema](#Code-First-Schema) section for more details.\n\n### Schema-First\n\nYou can define your GraphQL Schema from a file on disk. For convenience, use\nthe `appsync.Schema.fromAsset` to specify the file representing your schema.\n\n```python\napi = appsync.GraphqlApi(self, \"api\",\n name=\"myApi\",\n schema=appsync.Schema.from_asset(path.join(__dirname, \"schema.graphl\"))\n)\n```\n\n## Imports\n\nAny GraphQL Api that has been created outside the stack can be imported from\nanother stack into your CDK app. Utilizing the `fromXxx` function, you have\nthe ability to add data sources and resolvers through a `IGraphqlApi` interface.\n\n```python\n# api: appsync.GraphqlApi\n# table: dynamodb.Table\n\nimported_api = appsync.GraphqlApi.from_graphql_api_attributes(self, \"IApi\",\n graphql_api_id=api.api_id,\n graphql_api_arn=api.arn\n)\nimported_api.add_dynamo_db_data_source(\"TableDataSource\", table)\n```\n\nIf you don't specify `graphqlArn` in `fromXxxAttributes`, CDK will autogenerate\nthe expected `arn` for the imported api, given the `apiId`. For creating data\nsources and resolvers, an `apiId` is sufficient.\n\n## Authorization\n\nThere are multiple authorization types available for GraphQL API to cater to different\naccess use cases. They are:\n\n* API Keys (`AuthorizationType.API_KEY`)\n* Amazon Cognito User Pools (`AuthorizationType.USER_POOL`)\n* OpenID Connect (`AuthorizationType.OPENID_CONNECT`)\n* AWS Identity and Access Management (`AuthorizationType.AWS_IAM`)\n* AWS Lambda (`AuthorizationType.AWS_LAMBDA`)\n\nThese types can be used simultaneously in a single API, allowing different types of clients to\naccess data. When you specify an authorization type, you can also specify the corresponding\nauthorization mode to finish defining your authorization. For example, this is a GraphQL API\nwith AWS Lambda Authorization.\n\n```python\nimport aws_cdk.aws_lambda as lambda_\n# auth_function: lambda.Function\n\n\nappsync.GraphqlApi(self, \"api\",\n name=\"api\",\n schema=appsync.Schema.from_asset(path.join(__dirname, \"appsync.test.graphql\")),\n authorization_config=appsync.AuthorizationConfig(\n default_authorization=appsync.AuthorizationMode(\n authorization_type=appsync.AuthorizationType.LAMBDA,\n lambda_authorizer_config=appsync.LambdaAuthorizerConfig(\n handler=auth_function\n )\n )\n )\n)\n```\n\n## Permissions\n\nWhen using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role\nwith correct permissions must be used for access to API.\n\nWhen configuring permissions, you can specify specific resources to only be\naccessible by `IAM` authorization. For example, if you want to only allow mutability\nfor `IAM` authorized access you would configure the following.\n\nIn `schema.graphql`:\n\n```gql\ntype Mutation {\n updateExample(...): ...\n @aws_iam\n}\n```\n\nIn `IAM`:\n\n```json\n{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"appsync:GraphQL\"\n ],\n \"Resource\": [\n \"arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample\"\n ]\n }\n ]\n}\n```\n\nSee [documentation](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) for more details.\n\nTo make this easier, CDK provides `grant` API.\n\nUse the `grant` function for more granular authorization.\n\n```python\n# api: appsync.GraphqlApi\nrole = iam.Role(self, \"Role\",\n assumed_by=iam.ServicePrincipal(\"lambda.amazonaws.com\")\n)\n\napi.grant(role, appsync.IamResource.custom(\"types/Mutation/fields/updateExample\"), \"appsync:GraphQL\")\n```\n\n### IamResource\n\nIn order to use the `grant` functions, you need to use the class `IamResource`.\n\n* `IamResource.custom(...arns)` permits custom ARNs and requires an argument.\n* `IamResouce.ofType(type, ...fields)` permits ARNs for types and their fields.\n* `IamResource.all()` permits ALL resources.\n\n### Generic Permissions\n\nAlternatively, you can use more generic `grant` functions to accomplish the same usage.\n\nThese include:\n\n* grantMutation (use to grant access to Mutation fields)\n* grantQuery (use to grant access to Query fields)\n* grantSubscription (use to grant access to Subscription fields)\n\n```python\n# api: appsync.GraphqlApi\n# role: iam.Role\n\n\n# For generic types\napi.grant_mutation(role, \"updateExample\")\n\n# For custom types and granular design\napi.grant(role, appsync.IamResource.of_type(\"Mutation\", \"updateExample\"), \"appsync:GraphQL\")\n```\n\n## Pipeline Resolvers and AppSync Functions\n\nAppSync Functions are local functions that perform certain operations onto a\nbackend data source. Developers can compose operations (Functions) and execute\nthem in sequence with Pipeline Resolvers.\n\n```python\n# api: appsync.GraphqlApi\n\n\nappsync_function = appsync.AppsyncFunction(self, \"function\",\n name=\"appsync_function\",\n api=api,\n data_source=api.add_none_data_source(\"none\"),\n request_mapping_template=appsync.MappingTemplate.from_file(\"request.vtl\"),\n response_mapping_template=appsync.MappingTemplate.from_file(\"response.vtl\")\n)\n```\n\nAppSync Functions are used in tandem with pipeline resolvers to compose multiple\noperations.\n\n```python\n# api: appsync.GraphqlApi\n# appsync_function: appsync.AppsyncFunction\n\n\npipeline_resolver = appsync.Resolver(self, \"pipeline\",\n api=api,\n data_source=api.add_none_data_source(\"none\"),\n type_name=\"typeName\",\n field_name=\"fieldName\",\n request_mapping_template=appsync.MappingTemplate.from_file(\"beforeRequest.vtl\"),\n pipeline_config=[appsync_function],\n response_mapping_template=appsync.MappingTemplate.from_file(\"afterResponse.vtl\")\n)\n```\n\nLearn more about Pipeline Resolvers and AppSync Functions [here](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html).\n\n## Code-First Schema\n\nCDK offers the ability to generate your schema in a code-first approach.\nA code-first approach offers a developer workflow with:\n\n* **modularity**: organizing schema type definitions into different files\n* **reusability**: simplifying down boilerplate/repetitive code\n* **consistency**: resolvers and schema definition will always be synced\n\nThe code-first approach allows for **dynamic** schema generation. You can generate your schema based on variables and templates to reduce code duplication.\n\n### Code-First Example\n\nTo showcase the code-first approach. Let's try to model the following schema segment.\n\n```gql\ninterface Node {\n id: String\n}\n\ntype Query {\n allFilms(after: String, first: Int, before: String, last: Int): FilmConnection\n}\n\ntype FilmNode implements Node {\n filmName: String\n}\n\ntype FilmConnection {\n edges: [FilmEdge]\n films: [Film]\n totalCount: Int\n}\n\ntype FilmEdge {\n node: Film\n cursor: String\n}\n```\n\nAbove we see a schema that allows for generating paginated responses. For example,\nwe can query `allFilms(first: 100)` since `FilmConnection` acts as an intermediary\nfor holding `FilmEdges` we can write a resolver to return the first 100 films.\n\nIn a separate file, we can declare our object types and related functions.\nWe will call this file `object-types.ts` and we will have created it in a way that\nallows us to generate other `XxxConnection` and `XxxEdges` in the future.\n\n```python\nimport aws_cdk.aws_appsync as appsync\npluralize = require(\"pluralize\")\n\nargs = {\n \"after\": appsync.GraphqlType.string(),\n \"first\": appsync.GraphqlType.int(),\n \"before\": appsync.GraphqlType.string(),\n \"last\": appsync.GraphqlType.int()\n}\n\nNode = appsync.InterfaceType(\"Node\",\n definition={\"id\": appsync.GraphqlType.string()}\n)\nFilmNode = appsync.ObjectType(\"FilmNode\",\n interface_types=[Node],\n definition={\"film_name\": appsync.GraphqlType.string()}\n)\n\ndef generate_edge_and_connection(base):\n edge = appsync.ObjectType(f\"{base.name}Edge\",\n definition={\"node\": base.attribute(), \"cursor\": appsync.GraphqlType.string()}\n )\n connection = appsync.ObjectType(f\"{base.name}Connection\",\n definition={\n \"edges\": edge.attribute(is_list=True),\n \"pluralize(base.name)\": base.attribute(is_list=True),\n \"total_count\": appsync.GraphqlType.int()\n }\n )\n return {\"edge\": edge, \"connection\": connection}\n```\n\nFinally, we will go to our `cdk-stack` and combine everything together\nto generate our schema.\n\n```python\n# dummy_request: appsync.MappingTemplate\n# dummy_response: appsync.MappingTemplate\n\n\napi = appsync.GraphqlApi(self, \"Api\",\n name=\"demo\"\n)\n\nobject_types = [Node, FilmNode]\n\nfilm_connections = generate_edge_and_connection(FilmNode)\n\napi.add_query(\"allFilms\", appsync.ResolvableField(\n return_type=film_connections.connection.attribute(),\n args=args,\n data_source=api.add_none_data_source(\"none\"),\n request_mapping_template=dummy_request,\n response_mapping_template=dummy_response\n))\n\napi.add_type(Node)\napi.add_type(FilmNode)\napi.add_type(film_connections.edge)\napi.add_type(film_connections.connection)\n```\n\nNotice how we can utilize the `generateEdgeAndConnection` function to generate\nObject Types. In the future, if we wanted to create more Object Types, we can simply\ncreate the base Object Type (i.e. Film) and from there we can generate its respective\n`Connections` and `Edges`.\n\nCheck out a more in-depth example [here](https://github.com/BryanPan342/starwars-code-first).\n\n## GraphQL Types\n\nOne of the benefits of GraphQL is its strongly typed nature. We define the\ntypes within an object, query, mutation, interface, etc. as **GraphQL Types**.\n\nGraphQL Types are the building blocks of types, whether they are scalar, objects,\ninterfaces, etc. GraphQL Types can be:\n\n* [**Scalar Types**](https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html): Id, Int, String, AWSDate, etc.\n* [**Object Types**](#Object-Types): types that you generate (i.e. `demo` from the example above)\n* [**Interface Types**](#Interface-Types): abstract types that define the base implementation of other\n Intermediate Types\n\nMore concretely, GraphQL Types are simply the types appended to variables.\nReferencing the object type `Demo` in the previous example, the GraphQL Types\nis `String!` and is applied to both the names `id` and `version`.\n\n### Directives\n\n`Directives` are attached to a field or type and affect the execution of queries,\nmutations, and types. With AppSync, we use `Directives` to configure authorization.\nCDK provides static functions to add directives to your Schema.\n\n* `Directive.iam()` sets a type or field's authorization to be validated through `Iam`\n* `Directive.apiKey()` sets a type or field's authorization to be validated through a `Api Key`\n* `Directive.oidc()` sets a type or field's authorization to be validated through `OpenID Connect`\n* `Directive.cognito(...groups: string[])` sets a type or field's authorization to be validated\n through `Cognito User Pools`\n\n * `groups` the name of the cognito groups to give access\n\nTo learn more about authorization and directives, read these docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/security.html).\n\n### Field and Resolvable Fields\n\nWhile `GraphqlType` is a base implementation for GraphQL fields, we have abstractions\non top of `GraphqlType` that provide finer grain support.\n\n### Field\n\n`Field` extends `GraphqlType` and will allow you to define arguments. [**Interface Types**](#Interface-Types) are not resolvable and this class will allow you to define arguments,\nbut not its resolvers.\n\nFor example, if we want to create the following type:\n\n```gql\ntype Node {\n test(argument: string): String\n}\n```\n\nThe CDK code required would be:\n\n```python\nfield = appsync.Field(\n return_type=appsync.GraphqlType.string(),\n args={\n \"argument\": appsync.GraphqlType.string()\n }\n)\ntype = appsync.InterfaceType(\"Node\",\n definition={\"test\": field}\n)\n```\n\n### Resolvable Fields\n\n`ResolvableField` extends `Field` and will allow you to define arguments and its resolvers.\n[**Object Types**](#Object-Types) can have fields that resolve and perform operations on\nyour backend.\n\nYou can also create resolvable fields for object types.\n\n```gql\ntype Info {\n node(id: String): String\n}\n```\n\nThe CDK code required would be:\n\n```python\n# api: appsync.GraphqlApi\n# dummy_request: appsync.MappingTemplate\n# dummy_response: appsync.MappingTemplate\n\ninfo = appsync.ObjectType(\"Info\",\n definition={\n \"node\": appsync.ResolvableField(\n return_type=appsync.GraphqlType.string(),\n args={\n \"id\": appsync.GraphqlType.string()\n },\n data_source=api.add_none_data_source(\"none\"),\n request_mapping_template=dummy_request,\n response_mapping_template=dummy_response\n )\n }\n)\n```\n\nTo nest resolvers, we can also create top level query types that call upon\nother types. Building off the previous example, if we want the following graphql\ntype definition:\n\n```gql\ntype Query {\n get(argument: string): Info\n}\n```\n\nThe CDK code required would be:\n\n```python\n# api: appsync.GraphqlApi\n# dummy_request: appsync.MappingTemplate\n# dummy_response: appsync.MappingTemplate\n\nquery = appsync.ObjectType(\"Query\",\n definition={\n \"get\": appsync.ResolvableField(\n return_type=appsync.GraphqlType.string(),\n args={\n \"argument\": appsync.GraphqlType.string()\n },\n data_source=api.add_none_data_source(\"none\"),\n request_mapping_template=dummy_request,\n response_mapping_template=dummy_response\n )\n }\n)\n```\n\nLearn more about fields and resolvers [here](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html).\n\n### Intermediate Types\n\nIntermediate Types are defined by Graphql Types and Fields. They have a set of defined\nfields, where each field corresponds to another type in the system. Intermediate\nTypes will be the meat of your GraphQL Schema as they are the types defined by you.\n\nIntermediate Types include:\n\n* [**Interface Types**](#Interface-Types)\n* [**Object Types**](#Object-Types)\n* [**Enum Types**](#Enum-Types)\n* [**Input Types**](#Input-Types)\n* [**Union Types**](#Union-Types)\n\n#### Interface Types\n\n**Interface Types** are abstract types that define the implementation of other\nintermediate types. They are useful for eliminating duplication and can be used\nto generate Object Types with less work.\n\nYou can create Interface Types ***externally***.\n\n```python\nnode = appsync.InterfaceType(\"Node\",\n definition={\n \"id\": appsync.GraphqlType.string(is_required=True)\n }\n)\n```\n\nTo learn more about **Interface Types**, read the docs [here](https://graphql.org/learn/schema/#interfaces).\n\n#### Object Types\n\n**Object Types** are types that you declare. For example, in the [code-first example](#code-first-example)\nthe `demo` variable is an **Object Type**. **Object Types** are defined by\nGraphQL Types and are only usable when linked to a GraphQL Api.\n\nYou can create Object Types in two ways:\n\n1. Object Types can be created ***externally***.\n\n ```python\n api = appsync.GraphqlApi(self, \"Api\",\n name=\"demo\"\n )\n demo = appsync.ObjectType(\"Demo\",\n definition={\n \"id\": appsync.GraphqlType.string(is_required=True),\n \"version\": appsync.GraphqlType.string(is_required=True)\n }\n )\n\n api.add_type(demo)\n ```\n\n > This method allows for reusability and modularity, ideal for larger projects.\n > For example, imagine moving all Object Type definition outside the stack.\n\n `object-types.ts` - a file for object type definitions\n\n ```python\n import aws_cdk.aws_appsync as appsync\n demo = appsync.ObjectType(\"Demo\",\n definition={\n \"id\": appsync.GraphqlType.string(is_required=True),\n \"version\": appsync.GraphqlType.string(is_required=True)\n }\n )\n ```\n\n `cdk-stack.ts` - a file containing our cdk stack\n\n ```python\n # api: appsync.GraphqlApi\n\n api.add_type(demo)\n ```\n2. Object Types can be created ***externally*** from an Interface Type.\n\n ```python\n node = appsync.InterfaceType(\"Node\",\n definition={\n \"id\": appsync.GraphqlType.string(is_required=True)\n }\n )\n demo = appsync.ObjectType(\"Demo\",\n interface_types=[node],\n definition={\n \"version\": appsync.GraphqlType.string(is_required=True)\n }\n )\n ```\n\n > This method allows for reusability and modularity, ideal for reducing code duplication.\n\nTo learn more about **Object Types**, read the docs [here](https://graphql.org/learn/schema/#object-types-and-fields).\n\n#### Enum Types\n\n**Enum Types** are a special type of Intermediate Type. They restrict a particular\nset of allowed values for other Intermediate Types.\n\n```gql\nenum Episode {\n NEWHOPE\n EMPIRE\n JEDI\n}\n```\n\n> This means that wherever we use the type Episode in our schema, we expect it to\n> be exactly one of NEWHOPE, EMPIRE, or JEDI.\n\nThe above GraphQL Enumeration Type can be expressed in CDK as the following:\n\n```python\n# api: appsync.GraphqlApi\n\nepisode = appsync.EnumType(\"Episode\",\n definition=[\"NEWHOPE\", \"EMPIRE\", \"JEDI\"\n ]\n)\napi.add_type(episode)\n```\n\nTo learn more about **Enum Types**, read the docs [here](https://graphql.org/learn/schema/#enumeration-types).\n\n#### Input Types\n\n**Input Types** are special types of Intermediate Types. They give users an\neasy way to pass complex objects for top level Mutation and Queries.\n\n```gql\ninput Review {\n stars: Int!\n commentary: String\n}\n```\n\nThe above GraphQL Input Type can be expressed in CDK as the following:\n\n```python\n# api: appsync.GraphqlApi\n\nreview = appsync.InputType(\"Review\",\n definition={\n \"stars\": appsync.GraphqlType.int(is_required=True),\n \"commentary\": appsync.GraphqlType.string()\n }\n)\napi.add_type(review)\n```\n\nTo learn more about **Input Types**, read the docs [here](https://graphql.org/learn/schema/#input-types).\n\n#### Union Types\n\n**Union Types** are a special type of Intermediate Type. They are similar to\nInterface Types, but they cannot specify any common fields between types.\n\n**Note:** the fields of a union type need to be `Object Types`. In other words, you\ncan't create a union type out of interfaces, other unions, or inputs.\n\n```gql\nunion Search = Human | Droid | Starship\n```\n\nThe above GraphQL Union Type encompasses the Object Types of Human, Droid and Starship. It\ncan be expressed in CDK as the following:\n\n```python\n# api: appsync.GraphqlApi\n\nstring = appsync.GraphqlType.string()\nhuman = appsync.ObjectType(\"Human\", definition={\"name\": string})\ndroid = appsync.ObjectType(\"Droid\", definition={\"name\": string})\nstarship = appsync.ObjectType(\"Starship\", definition={\"name\": string})\nsearch = appsync.UnionType(\"Search\",\n definition=[human, droid, starship]\n)\napi.add_type(search)\n```\n\nTo learn more about **Union Types**, read the docs [here](https://graphql.org/learn/schema/#union-types).\n\n### Query\n\nEvery schema requires a top level Query type. By default, the schema will look\nfor the `Object Type` named `Query`. The top level `Query` is the **only** exposed\ntype that users can access to perform `GET` operations on your Api.\n\nTo add fields for these queries, we can simply run the `addQuery` function to add\nto the schema's `Query` type.\n\n```python\n# api: appsync.GraphqlApi\n# film_connection: appsync.InterfaceType\n# dummy_request: appsync.MappingTemplate\n# dummy_response: appsync.MappingTemplate\n\n\nstring = appsync.GraphqlType.string()\nint = appsync.GraphqlType.int()\napi.add_query(\"allFilms\", appsync.ResolvableField(\n return_type=film_connection.attribute(),\n args={\"after\": string, \"first\": int, \"before\": string, \"last\": int},\n data_source=api.add_none_data_source(\"none\"),\n request_mapping_template=dummy_request,\n response_mapping_template=dummy_response\n))\n```\n\nTo learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-overview.html).\n\n### Mutation\n\nEvery schema **can** have a top level Mutation type. By default, the schema will look\nfor the `ObjectType` named `Mutation`. The top level `Mutation` Type is the only exposed\ntype that users can access to perform `mutable` operations on your Api.\n\nTo add fields for these mutations, we can simply run the `addMutation` function to add\nto the schema's `Mutation` type.\n\n```python\n# api: appsync.GraphqlApi\n# film_node: appsync.ObjectType\n# dummy_request: appsync.MappingTemplate\n# dummy_response: appsync.MappingTemplate\n\n\nstring = appsync.GraphqlType.string()\nint = appsync.GraphqlType.int()\napi.add_mutation(\"addFilm\", appsync.ResolvableField(\n return_type=film_node.attribute(),\n args={\"name\": string, \"film_number\": int},\n data_source=api.add_none_data_source(\"none\"),\n request_mapping_template=dummy_request,\n response_mapping_template=dummy_response\n))\n```\n\nTo learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-overview.html).\n\n### Subscription\n\nEvery schema **can** have a top level Subscription type. The top level `Subscription` Type\nis the only exposed type that users can access to invoke a response to a mutation. `Subscriptions`\nnotify users when a mutation specific mutation is called. This means you can make any data source\nreal time by specify a GraphQL Schema directive on a mutation.\n\n**Note**: The AWS AppSync client SDK automatically handles subscription connection management.\n\nTo add fields for these subscriptions, we can simply run the `addSubscription` function to add\nto the schema's `Subscription` type.\n\n```python\n# api: appsync.GraphqlApi\n# film: appsync.InterfaceType\n\n\napi.add_subscription(\"addedFilm\", appsync.Field(\n return_type=film.attribute(),\n args={\"id\": appsync.GraphqlType.id(is_required=True)},\n directives=[appsync.Directive.subscribe(\"addFilm\")]\n))\n```\n\nTo learn more about top level operations, check out the docs [here](https://docs.aws.amazon.com/appsync/latest/devguide/real-time-data.html).\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::AppSync",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "60e8c95e0d20d2e125eaa9794967916ea46c4eeb83ef3ee1c3d800a12a66dbf9",
"md5": "80c16ba41b96a9ff8d188dd5ceb4ab58",
"sha256": "901372a55603e51261357aed1981986621fd6e5ffb1107429a31eaa177ef64c1"
},
"downloads": -1,
"filename": "aws_cdk.aws_appsync-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80c16ba41b96a9ff8d188dd5ceb4ab58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 480134,
"upload_time": "2023-05-31T22:52:47",
"upload_time_iso_8601": "2023-05-31T22:52:47.940965Z",
"url": "https://files.pythonhosted.org/packages/60/e8/c95e0d20d2e125eaa9794967916ea46c4eeb83ef3ee1c3d800a12a66dbf9/aws_cdk.aws_appsync-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "158ef1dd14fe4de9ff97073e9332ffa36629a335739d142a34a056b2c4e0bb7f",
"md5": "ef529557614476a8405ce3365d370d2b",
"sha256": "38883340ac59e46d5bb8d87613110510931754bf9dd260914384848a8d494804"
},
"downloads": -1,
"filename": "aws-cdk.aws-appsync-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "ef529557614476a8405ce3365d370d2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 488056,
"upload_time": "2023-05-31T23:00:46",
"upload_time_iso_8601": "2023-05-31T23:00:46.255551Z",
"url": "https://files.pythonhosted.org/packages/15/8e/f1dd14fe4de9ff97073e9332ffa36629a335739d142a34a056b2c4e0bb7f/aws-cdk.aws-appsync-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:00:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-appsync"
}
JSON
