Metadata-Version: 2.1
Name: aws-cdk.aws-appsync
Version: 1.61.0
Summary: The CDK Construct Library for AWS::AppSync
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Description: ## AWS AppSync Construct Library
        
        <!--BEGIN STABILITY BANNER-->---
        
        
        ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
        
        > 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.
        
        ![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
        
        > 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.
        
        ### Example
        
        Example of a GraphQL API with `AWS_IAM` authorization resolving into a DynamoDb
        backend data source.
        
        GraphQL schema file `schema.graphql`:
        
        ```gql
        type demo {
          id: String!
          version: String!
        }
        type Query {
          getDemos: [ test! ]
        }
        input DemoInput {
          version: String!
        }
        type Mutation {
          addDemo(input: DemoInput!): demo
        }
        ```
        
        CDK stack file `app-stack.ts`:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        import aws_cdk.aws_appsync as appsync
        import aws_cdk.aws_dynamodb as db
        
        api = appsync.GraphQLApi(stack, "Api",
            name="demo",
            schema=appsync.Schema.from_asset(join(__dirname, "schema.graphql")),
            authorization_config=AuthorizationConfig(
                default_authorization=AuthorizationMode(
                    authorization_type=appsync.AuthorizationType.IAM
                )
            ),
            xray_enabled=True
        )
        
        demo_table = db.Table(stack, "DemoTable",
            partition_key=Attribute(
                name="id",
                type=db.AttributeType.STRING
            )
        )
        
        demo_dS = api.add_dynamo_db_data_source("demoDataSource", demo_table)
        
        # Resolver for the Query "getDemos" that scans the DyanmoDb table and returns the entire list.
        demo_dS.create_resolver(
            type_name="Query",
            field_name="getDemos",
            request_mapping_template=MappingTemplate.dynamo_db_scan_table(),
            response_mapping_template=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=MappingTemplate.dynamo_db_put_item(PrimaryKey.partition("id").auto(), Values.projecting("demo")),
            response_mapping_template=MappingTemplate.dynamo_db_result_item()
        )
        ```
        
        ### 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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = 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.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        schema = appsync.Schema()
        schema.add_object_type("demo",
            definition={"id": appsync.GraphqlType.id()}
        )
        api = appsync.GraphQLApi(stack, "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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        api = appsync.GraphQLApi(stack, "api",
            name="myApi",
            schema=appsync.Schema.from_asset(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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        imported_api = appsync.GraphQLApi.from_graph_qLApi_attributes(stack, "IApi",
            graphql_api_id=api.api_id,
            graphql_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.
        
        ### 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`:
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        role = iam.Role(stack, "Role",
            assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
        )
        api = appsync.GraphQLApi(stack, "API",
            definition=definition
        )
        
        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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        # 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")
        ```
        
        ## 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 scalar types: `scalar-types.ts`.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        from aws_cdk.aws_appsync import GraphqlType
        
        string = appsync.GraphqlType.string()
        int = appsync.GraphqlType.int()
        ```
        
        In another 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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        pluralize = require("pluralize")
        import ..scalar_types.ts as scalar
        import aws_cdk.aws_appsync as appsync
        
        args = {
            "after": scalar.string,
            "first": scalar.int,
            "before": scalar.string,
            "last": scalar.int
        }
        
        Node = appsync.InterfaceType("Node", {
            "definition": {"id": scalar.string}
        })
        FilmNode = appsync.ObjectType.implement_interface("FilmNode",
            interface_types=[Node],
            definition={"film_name": scalar.string}
        )
        
        def generate_edge_and_connection(base):
            edge = appsync.ObjectType(f"{base.name}Edge",
                definition={"node": base.attribute(), "cursor": scalar.string}
            )
            connection = appsync.ObjectType(f"{base.name}Connection",
                definition={
                    "edges": edges.attribute(is_list=True),
                    "[pluralize(base.name)]": base.attribute(is_list=True),
                    "total_count": scalar.int
                }
            )return {"edge": edge, "connection": connection}
        ```
        
        Finally, we will go to our `cdk-stack` and combine everything together
        to generate our schema.
        
        ```python
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        import aws_cdk.aws_appsync as appsync
        import ..object_types as schema
        
        api = appsync.GraphQLApi(stack, "Api",
            name="demo"
        )
        
        self.object_types = [schema.Node, schema.Film]
        
        film_connections = schema.generate_edge_and_connection(schema.Film)
        
        api.add_type("Query",
            definition={
                "all_films": appsync.ResolvableField(dummy_data_source,
                    return_type=film_connections.connection.attribute(),
                    args=schema.args,
                    request_mapping_template=dummy_request,
                    response_mapping_template=dummy_response
                )
            }
        )
        
        self.object_types.map((t) => api.addType(t))
        Object.keys(film_connections).for_each((key) => api.addType(filmConnections[key]))
        ```
        
        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`.
        
        ### 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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        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)
        
        ### 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
        # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
        node = appsync.InterfaceType("Node",
            definition={
                "id": appsync.GraphqlType.string(is_required=True)
            }
        )
        ```
        
        ### 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***.
        
           ```python
           # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
           api = appsync.GraphQLApi(stack, "Api",
               name="demo"
           )
           demo = appsync.ObjectType("Demo",
               defintion={
                   "id": appsync.GraphqlType.string(is_required=True),
                   "version": appsync.GraphqlType.string(is_required=True)
               }
           )
        
           api.add_type(object)
           ```
        
           > 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
        
           ```python
           # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
           required_string = appsync.GraphqlType.string(is_required=True)
           ```
        
           `object-types.ts` - a file for object type definitions
        
           ```python
           # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
           from ..scalar_types import required_string
           demo = appsync.ObjectType("Demo",
               defintion={
                   "id": required_string,
                   "version": required_string
               }
           )
           ```
        
           `cdk-stack.ts` - a file containing our cdk stack
        
           ```python
           # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
           from ..object_types import demo
           api.add_type(demo)
           ```
        2. Object Types can be created ***externally*** from an Interface Type.
        
           ```python
           # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
           node = appsync.InterfaceType("Node",
               definition={
                   "id": appsync.GraphqlType.string(is_required=True)
               }
           )
           demo = appsync.ObjectType("Demo",
               interface_types=[node],
               defintion={
                   "version": appsync.GraphqlType.string(is_required=True)
               }
           )
           ```
        
           > This method allows for reusability and modularity, ideal for reducing code duplication.
        3. Object Types can be created ***internally*** within the GraphQL API.
        
           ```python
           # Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
           api = appsync.GraphQLApi(stack, "Api",
               name="demo"
           )
           api.add_type("Demo",
               defintion={
                   "id": appsync.GraphqlType.string(is_required=True),
                   "version": appsync.GraphqlType.string(is_required=True)
               }
           )
           ```
        
           > This method provides easy use and is ideal for smaller projects.
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Typing :: Typed
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved
Requires-Python: >=3.6
Description-Content-Type: text/markdown
