GraphQL HTTP Transformer

Common errors

• Error: Unknown directive "@http".

  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.
  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.

• An error occurred during the push operation: Your GraphQL Schema is using "@key" directive from an older version of the GraphQL Transformer.

  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.
  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.

• The authorization header is invalid for the HTTP data source.

  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.
  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.

• Response code 4xx/5xx for HTTP data source invocation.

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install graphql-http-transformer npm
• yarn add graphql-http-transformer yarn
• pnpm add graphql-http-transformer pnpm

Imports

• HttpTransformer
  wrong:

  const HttpTransformer = require('graphql-http-transformer');

  correct:

  import { HttpTransformer } from 'graphql-http-transformer';

  The package primarily exports the HttpTransformer class for programmatic use in a transformer pipeline. ESM import is standard for modern Amplify projects.
• TransformerFactory
  wrong:

  import { TransformerFactory } from 'graphql-http-transformer';

  correct:

  import { TransformerFactory } from '@aws-amplify/graphql-transformer-core';

  While HttpTransformer is the specific HTTP resolver, TransformerFactory from 'graphql-transformer-core' is the orchestrator for applying multiple transformers to a schema.
• buildSchema
  wrong:

  import { buildSchema } from 'graphql-http-transformer';

  correct:

  import { buildSchema } from 'graphql';

  When working with GraphQL schema definitions programmatically, `buildSchema` from the `graphql` package is essential for parsing schema strings into executable schema objects.

Quickstart

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.

/* src/schema.graphql */
# This file defines your GraphQL API schema with the @http directive.
# The graphql-http-transformer processes this directive when you use the Amplify CLI
# to provision AWS AppSync HTTP Data Sources and Resolvers automatically.

type Query {
  # Defines a GraphQL query 'getPost' that fetches data from an external HTTP API.
  # The @http directive configures the AppSync resolver to make a GET request.
  # The 'url' argument dynamically constructs the URL using the '$id' argument.
  getPost(id: ID!): Post @http(method: GET, url: "https://jsonplaceholder.typicode.com/posts/${id}")

  # Example of a mutation using a POST request to an external API.
  createTodo(input: CreateTodoInput!): Todo @http(method: POST, url: "https://api.example.com/todos")
}

type Post {
  id: ID!
  title: String
  body: String
  userId: ID
}

input CreateTodoInput {
  title: String!
  description: String
  completed: Boolean = false
}

type Todo {
  id: ID!
  title: String!
  description: String
  completed: Boolean
}

# To deploy this schema with AWS Amplify, you would typically use the Amplify CLI:
# 1. Initialize an Amplify project: `amplify init`
# 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)
# 3. Push changes to the cloud: `amplify push`
# The CLI will detect the @http directive, apply the transformer, and provision
# the necessary AWS resources (AppSync API, HTTP Data Sources, Resolvers).