graphql-http-transformer is an AWS Amplify component, specifically an AppSync model transform that facilitates the integration of GraphQL APIs with external HTTP/REST endpoints. It processes the `@http` GraphQL directive within a schema, automatically generating AWS AppSync HTTP data sources and VTL (Velocity Template Language) resolvers. This allows developers to seamlessly proxy GraphQL operations to existing external services without writing custom VTL or AWS CloudFormation. The package is currently at version `5.2.80` and is part of the larger `@aws-amplify/amplify-category-api` monorepo, indicating an active development lifecycle with releases tied to the broader Amplify ecosystem updates. Its key differentiators include deep integration with the Amplify CLI/CDK for streamlined deployment, automatic resource provisioning, and support for dynamic URL construction, enabling a declarative approach to connecting AppSync to diverse backend services.
npm install graphql-http-transformerVerified import paths — ran on the pinned version, not inferred.
Demonstrates defining a GraphQL schema with the `@http` directive for an AWS Amplify project, outlining how it generates AppSync HTTP resolvers for external API integration.
Consult the AWS Amplify CLI documentation for GraphQL Transformer v1 to v2 migration guide. Update your `amplify/cli.json` to specify `"transformerversion": 2` and adjust your schema and custom resolvers as needed.
Ensure the AppSync service role associated with your API has `sts:AssumeRole` and `execute-api:Invoke` (or specific service actions if the endpoint is an AWS service) permissions for the target HTTP endpoints. Review CloudWatch logs for detailed access denied messages.
Always use `${argumentName}` syntax for dynamic parameters in the `@http` `url` field. Test thoroughly with various input values to ensure correct URL formation and parameter passing, especially for path parameters and query strings.Optimize external HTTP endpoint performance. Implement pagination and field selection where possible to reduce payload size. For long-running operations, consider using AWS Lambda functions with `@function` directive for asynchronous processing and returning results via subscriptions.
Implement robust authorization using the `@auth` directive on your GraphQL types and fields. Ensure external HTTP endpoints are also secured (e.g., API keys in request headers, IP whitelisting) and that sensitive information is not directly exposed. Avoid connecting to internal APIs without strict network controls.
Ensure `graphql-http-transformer` is a dependency in your Amplify project and that you are using a compatible Amplify CLI version (`npm install -g @aws-amplify/cli@latest`). Run `amplify push` to re-trigger the transformer pipeline.
Migrate your GraphQL schema to Transformer v2 syntax. Specifically, address directives like `@key` (now `@primaryKey` and `@index`), `@connection` (now `@hasOne`, `@hasMany`, etc.), and review `@auth` rules. Refer to the official Amplify migration guide.
Review the `@http` directive's `headers` argument and ensure any necessary API keys, tokens, or other authorization details are correctly configured as environment variables or secrets and securely passed. Verify the external API's expected authorization mechanism.
Examine the `url`, `method`, `headers`, `query`, and `body` arguments of your `@http` directive for correctness. Use tools like `curl` or a browser to test the external endpoint directly with the expected payload to diagnose the error from the external service. Enable AppSync logging to CloudWatch for detailed resolver execution traces.