{"id":16371,"library":"graphql-http-transformer","title":"GraphQL HTTP Transformer","description":"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.","status":"active","version":"5.2.80","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-category-api","tags":["javascript","graphql","appsync","aws","typescript"],"install":[{"cmd":"npm install graphql-http-transformer","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-http-transformer","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-http-transformer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for GraphQL transformers in Amplify, providing the framework for applying directives.","package":"@aws-amplify/graphql-transformer-core","optional":false},{"reason":"Used for GraphQL schema parsing, validation, and manipulation.","package":"graphql","optional":false}],"imports":[{"note":"The package primarily exports the HttpTransformer class for programmatic use in a transformer pipeline. ESM import is standard for modern Amplify projects.","wrong":"const HttpTransformer = require('graphql-http-transformer');","symbol":"HttpTransformer","correct":"import { HttpTransformer } from 'graphql-http-transformer';"},{"note":"While HttpTransformer is the specific HTTP resolver, TransformerFactory from 'graphql-transformer-core' is the orchestrator for applying multiple transformers to a schema.","wrong":"import { TransformerFactory } from 'graphql-http-transformer';","symbol":"TransformerFactory","correct":"import { TransformerFactory } from '@aws-amplify/graphql-transformer-core';"},{"note":"When working with GraphQL schema definitions programmatically, `buildSchema` from the `graphql` package is essential for parsing schema strings into executable schema objects.","wrong":"import { buildSchema } from 'graphql-http-transformer';","symbol":"buildSchema","correct":"import { buildSchema } from 'graphql';"}],"quickstart":{"code":"/* src/schema.graphql */\n# This file defines your GraphQL API schema with the @http directive.\n# The graphql-http-transformer processes this directive when you use the Amplify CLI\n# to provision AWS AppSync HTTP Data Sources and Resolvers automatically.\n\ntype Query {\n  # Defines a GraphQL query 'getPost' that fetches data from an external HTTP API.\n  # The @http directive configures the AppSync resolver to make a GET request.\n  # The 'url' argument dynamically constructs the URL using the '$id' argument.\n  getPost(id: ID!): Post @http(method: GET, url: \"https://jsonplaceholder.typicode.com/posts/${id}\")\n\n  # Example of a mutation using a POST request to an external API.\n  createTodo(input: CreateTodoInput!): Todo @http(method: POST, url: \"https://api.example.com/todos\")\n}\n\ntype Post {\n  id: ID!\n  title: String\n  body: String\n  userId: ID\n}\n\ninput CreateTodoInput {\n  title: String!\n  description: String\n  completed: Boolean = false\n}\n\ntype Todo {\n  id: ID!\n  title: String!\n  description: String\n  completed: Boolean\n}\n\n# To deploy this schema with AWS Amplify, you would typically use the Amplify CLI:\n# 1. Initialize an Amplify project: `amplify init`\n# 2. Add an API: `amplify add api` (choose GraphQL, then select 'Single object with fields (e.g., \"Todo\")' or 'Blank schema' and paste the above content)\n# 3. Push changes to the cloud: `amplify push`\n# The CLI will detect the @http directive, apply the transformer, and provision\n# the necessary AWS resources (AppSync API, HTTP Data Sources, Resolvers).","lang":"graphql","description":"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."},"warnings":[{"fix":"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.","message":"Migration from GraphQL Transformer v1 to v2 (Amplify CLI v8+). The underlying architecture of GraphQL transformers significantly changed to leverage AWS AppSync Pipeline Resolvers. While `@http` directive syntax is largely compatible, other related directives like `@auth`, `@key`, and custom resolvers require manual migration steps.","severity":"breaking","affected_versions":"<5.0.0"},{"fix":"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.","message":"Incorrect IAM permissions for generated HTTP resolvers. The AppSync service role must have appropriate permissions to invoke the external HTTP endpoints. Misconfigured IAM policies often lead to 'Unauthorized' errors at runtime.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Dynamic URL construction and argument interpolation. Using variables in `@http` directive URLs requires specific syntax (`${variableName}`). Incorrect escaping or interpolation logic can lead to malformed requests to the external endpoint.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"HTTP data source limitations and performance. AppSync HTTP resolvers have timeouts and payload size limits. Relying on very slow external APIs or returning extremely large payloads can lead to timeouts or truncated responses.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"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.","message":"Security considerations for exposing HTTP endpoints. Direct integration with external HTTP APIs via AppSync can potentially expose internal services or sensitive endpoints if not properly secured with authentication and authorization.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"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.","cause":"The `graphql-http-transformer` or the necessary Amplify CLI version is not correctly installed or enabled, preventing the `@http` directive from being recognized during schema transformation.","error":"Error: Unknown directive \"@http\"."},{"fix":"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.","cause":"This specific error, while mentioning `@key`, indicates an incompatibility between your schema (potentially using old directive patterns) and the GraphQL Transformer version configured in your Amplify project. It commonly arises during attempted upgrades or when mixing v1 and v2 transformer schemas.","error":"An error occurred during the push operation: Your GraphQL Schema is using \"@key\" directive from an older version of the GraphQL Transformer."},{"fix":"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.","cause":"The AWS AppSync resolver generated by `@http` tried to access the external HTTP endpoint, but the request was rejected due to missing or incorrect authorization credentials (e.g., API keys, IAM credentials, OAuth tokens) in the request headers or body.","error":"The authorization header is invalid for the HTTP data source."},{"fix":"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.","cause":"The external HTTP endpoint returned a client-side (4xx) or server-side (5xx) error, indicating an issue with the request sent by the AppSync resolver or an error within the external service itself.","error":"Response code 4xx/5xx for HTTP data source invocation."}],"ecosystem":"npm"}