Registry / aws / graphql-http-transformer

graphql-http-transformer

JSON →
library5.2.80jsnpmunverified

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-transformer
INSTALL
IMPORT
SIG · GRAPHQL-HTTP-TRANS
G
graphql-http-transformer
awsjavascriptv5.2.80
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HttpTransformer
import { HttpTransformer } from 'graphql-http-transformer';
const HttpTransformer = require('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
import { TransformerFactory } from '@aws-amplify/graphql-transformer-core';
import { TransformerFactory } from 'graphql-http-transformer';
While HttpTransformer is the specific HTTP resolver, TransformerFactory from 'graphql-transformer-core' is the orchestrator for applying multiple transformers to a schema.
buildSchema
import { buildSchema } from 'graphql';
import { buildSchema } from 'graphql-http-transformer';
When working with GraphQL schema definitions programmatically, `buildSchema` from the `graphql` package is essential for parsing schema strings into executable schema objects.

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).
Debug
Known issues
breakingMigration 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.
affects: <5.0.0
gotchaIncorrect 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.
affects: >=1.0.0
gotchaDynamic 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.
affects: >=1.0.0
gotchaHTTP 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.
affects: >=1.0.0
gotchaSecurity 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Unknown directive "@http".
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.
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.
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.
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.
Upgrade
Version history
5.2.80latest on npm
Audit
Dependencies
@aws-amplify/graphql-transformer-corerequiredCore library for GraphQL transformers in Amplify, providing the framework for applying directives.
graphqlrequiredUsed for GraphQL schema parsing, validation, and manipulation.
Agent activity
15 hits · last 30 days
node
12
Resources
graphql-http-transformer — npm install graphql-http-transformer · libregistry