GraphQL API

Resource Overview

A GraphQL API represents an AWS AppSync GraphQL API. AWS AppSync is a GraphQL service that offers developers more flexibility and efficiency when implementing an API.

Key Benefits of AWS AppSync include:

• Fully-managed by AWS
• Reduces data fetching traffic and improves performance
• Real-time and offline access to users' data
• Ability to build applications from multiple sources

There are trade-offs that developers need to consider when choosing between a GraphQL API and a traditional REST API. A REST API offers multiple endpoints to access certain resources in a data source. If a client requests records from multiple resources, it requires multiple round-trips to each endpoint to gather that data. This leads to over-fetching of information with no way for the client to control what data is returned to them.

GraphQL is a query language that allows clients to declaratively communicate their data requirements from a data source. Instead of multiple endpoints, GraphQL treats the entire data source as one endpoint, using its declarative query language to gather and return custom data in one round-trip. Users are able to connect to any AppSync supported data source, specify what data they want, in the format they want it in.

When implementing a GraphQL API into your application, you need to declare and configure three main features:

Schema

Describes the capabilities of your API and is needed for query validation. You specify what actions your API can perform on your data by defining GraphQL operations like queries, mutations, or subscriptions. Utilize this AWS documentation to help design your GraphQL schema.

Data Source

Stores the data that your serverless application requires. Data sources can be AppSync supported resources like AWS Lambda and Amazon DynamoDB, as well as external sources like an existing REST API fronting a database.

Resolvers

Schemas and data sources are connected by GraphQL resolvers, which fulfill your data fetching requests. Once a schema has been defined on your GraphQL API, the last option is to attach resolvers, which can be configured by referencing the GraphQL Resolvers resource documentation.

Configurable Properties

Display Name

Human readable name for this resource that is displayed on the Stackery Dashboard and Stackery CLI output.

Authentication Type

Specify the authentication type required for applications to gain access to your GraphQL API. GraphQL API currently supports the following four authentication types:

• API Key (Default)
• AWS IAM Signatures
• AWS Cognito User Pools
• OpenID Connect

Field-Level Logging

Specify which field resolvers in your GraphQL API will emit logs. Logs are considered 'field-level' because they give you access to individual resolver logging. Details on what Field-Level Logs consist of can be found here.

• All Queries: All field resolvers will output logs
• Erroring Queries: only fields with errors (default)
• None: no logs from field resolvers

Save Schema in File

Enabling this option will save your GraphQL schema in a .graphql file and store it in this stack's git repository. This option is enabled by default.

Schema File Location

Specify the location of the schema file as it relates to your stack's git repository.

GraphQL Schema

This schema defines your GraphQL's capabilities. You define the shape of your data, what operations can be performed on it. All data operations that run through your GraphQL API will be validated against this schema, giving you more control. Utilize this AWS documentation to help design your GraphQL schema.

Attach Resolvers

A correctly formatted schema will populate this drop-down menu displaying the available GraphQL Resolvers for your API. Once a GraphQL Resolver is attached and the configuration is saved, double-click on the resulting GraphQL Resolver resource on the Stack Editor to begin configuring. Reference the GraphQL Resolver resource documentation for configuration options.

IAM Permissions

When connected by a service discovery wire (dashed wire), a Function or Docker Task will add the following IAM policy to its role and gain permission to access this resource.

No Permissions Added

Environment Variables

When connected by a service discovery wire (dashed wire), a Function or Docker Task will automatically populate and reference the following environment variables in order to interact with this resource.

No Available Environment Variables

Metrics & Logs

Double clicking a resource while viewing your stack's current deployment gives you access to your pre-configured resource properties, and links to the following metrics and logs.

• Logs

Related AWS Documentation

AWS Documentation: AWS::AppSync::GraphQLAPI