Skip to main content

GraphQLApi

caution

This is the SST v1.x Constructs doc. SST v2 is now released. If you are using v2, see the v2 Constructs doc. If you are looking to upgrade to v2, check out the upgrade steps.

The GraphQLApi construct is a higher level CDK construct that makes it easy to create GraphQL servers with AWS Lambda. It provides a simple way to define the GraphQL handler route in your API. And allows you to configure the specific Lambda function if necessary. It also allows you to configure authorization, custom domains, etc.

The GraphQLApi construct internally extends the Api construct.

warning

The GraphQLApi construct is deprecated, and will be removed in SST v2. Use the Api construct with a graphql route instead. Read more about how to upgrade.

Examples​

Using the minimal config​

import { GraphQLApi } from "@serverless-stack/resources";

new GraphQLApi(stack, "Api", {
  server: "src/graphql.handler",
});

Configuring routes​

You can configure the Lambda function used for the GraphQL Server.

new GraphQLApi(stack, "Api", {
  server: {
    handler: "src/graphql.handler",
    timeout: 10,
    memorySize: 512,
  },
});

Custom domains​

new GraphQLApi(stack, "Api", {
  customDomain: "api.domain.com",
  server: "src/graphql.handler",
});

Authorization​

You can secure your APIs (and other AWS resources) by setting the default.authorizer.

new GraphQLApi(stack, "Api", {
  defaults: {
    authorizer: "iam",
  },
  server: "src/graphql.handler",
});

Access log​

Use a CSV format instead of default JSON format.

new GraphQLApi(stack, "Api", {
  accessLog:
    "$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId",
  server: "src/graphql.handler",
});

CORS​

Override the default behavior of allowing all methods, and only allow the GET method.

new GraphQLApi(stack, "Api", {
  cors: {
    allowMethods: ["GET"],
  },
  server: "src/graphql.handler",
});

More examples​

For more examples, refer to the Api examples.

Constructor​

new GraphQLApi(scope, id, props)

Parameters

GraphQLApiProps​

accessLog?​

Type : string | boolean | ApiAccessLogProps

Default : true

Enable CloudWatch access logs for this API

new GraphQLApi(stack, "Api", {
  accessLog: true
});
new GraphQLApi(stack, "Api", {
  accessLog: {
    retention: "one_week",
  },
});

authorizers?​

Type : Record<string, ApiUserPoolAuthorizer | ApiJwtAuthorizer | ApiLambdaAuthorizer>

Define the authorizers for the API. Can be a user pool, JWT, or Lambda authorizers.

new GraphQLApi(stack, "Api", {
  authorizers: {
    Authorizer: {
      type: "user_pool",
      userPool: {
        id: userPool.userPoolId,
        clientIds: [userPoolClient.userPoolClientId],
      },
    },
  },
});

codegen?​

Type : string

Path to graphql-codegen configuration file

new GraphQLApi(stack, "api", {
  codegen: "./graphql/codegen.yml"
})

cors?​

Type : boolean | ApiCorsProps

Default : true

CORS support applied to all endpoints in this API

new GraphQLApi(stack, "Api", {
  cors: {
    allowMethods: ["GET"],
  },
});

customDomain?​

Type : string | ApiDomainProps

Specify a custom domain to use in addition to the automatically generated one. SST currently supports domains that are configured using Route 53

new GraphQLApi(stack, "Api", {
  customDomain: "api.example.com"
})
new GraphQLApi(stack, "Api", {
  customDomain: {
    domainName: "api.example.com",
    hostedZone: "domain.com",
    path: "v1"
  }
})

defaults.authorizationScopes?​

Type : Array<string>

Default : []

An array of scopes to include in the authorization when using user_pool or jwt authorizers. These will be merged with the scopes from the attached authorizer.

defaults.authorizer?​

Type : "none" | "iam" | Omit<string, "none" | "iam">

The default authorizer for all the routes in the API.

new GraphQLApi(stack, "Api", {
  defaults: {
    authorizer: "iam",
  }
});
new GraphQLApi(stack, "Api", {
  authorizers: {
    Authorizer: {
      type: "user_pool",
      userPool: {
        id: userPool.userPoolId,
        clientIds: [userPoolClient.userPoolClientId],
      },
    },
  },
  defaults: {
    authorizer: "Authorizer",
  }
});

defaults.function?​

Type : FunctionProps

The default function props to be applied to all the Lambda functions in the API. The environment, permissions and layers properties will be merged with per route definitions if they are defined.

new GraphQLApi(stack, "Api", {
  defaults: {
    function: {
      timeout: 20,
      environment: { tableName: table.tableName },
      permissions: [table],
    }
  }
});

defaults.payloadFormatVersion?​

Type : "1.0" | "2.0"

Default : "2.0"

The payload format version for all the endpoints in the API.

defaults.throttle.burst?​

Type : number

The burst rate of the number of concurrent request for all the routes in the API.

new GraphQLApi(stack, "Api", {
  defaults: {
    throttle: {
      burst: 100
    }
  }
})

defaults.throttle.rate?​

Type : number

The steady-state rate of the number of concurrent request for all the routes in the API.

new GraphQLApi(stack, "Api", {
  defaults: {
    throttle: {
      rate: 10
    }
  }
})

rootPath?​

Type : string

server​

Type : string | Function | FunctionProps

Path to function that will be invoked to resolve GraphQL queries.

new GraphQLApi(stack, "api", {
  codegen: "./graphql/codegen.yml"
})

cdk.httpApi?​

Type : IHttpApi | HttpApiProps

Import the underlying HTTP API or override the default configuration

import { HttpApi } from "@aws-cdk/aws-apigatewayv2-alpha";

new GraphQLApi(stack, "Api", {
  cdk: {
    httpApi: HttpApi.fromHttpApiAttributes(stack, "MyHttpApi", {
      httpApiId,
    }),
  }
});

cdk.httpStages?​

Type : Array<Omit<HttpStageProps, "httpApi">>

Configures the stages to create for the HTTP API. Note that, a default stage is automatically created, unless the cdk.httpApi.createDefaultStage is set to `false.

import { HttpApi } from "@aws-cdk/aws-apigatewayv2-alpha";

new GraphQLApi(stack, "Api", {
  cdk: {
    httpStages: [{
      stageName: "dev",
      autoDeploy: false,
    }],
  }
});

cdk.id?​

Type : string

Allows you to override default id for this construct.

Properties​

An instance of GraphQLApi has the following properties.

customDomainUrl​

Type : undefined | string

If custom domain is enabled, this is the custom domain URL of the Api.

note

If you are setting the base mapping for the custom domain, you need to include the trailing slash while using the custom domain URL. For example, if the domainName is set to api.domain.com and the path is v1, the custom domain URL of the API will be https://api.domain.com/v1/.

httpApiArn​

Type : string

The ARN of the internally created API Gateway HTTP API

httpApiId​

Type : string

The id of the internally created API Gateway HTTP API

id​

Type : string

routes​

Type : Array<string>

The routes for the Api

serverFunction​

Type : Function

url​

Type : string

The AWS generated URL of the Api.

cdk.accessLogGroup?​

Type : LogGroup

If access logs are enabled, this is the internally created CDK LogGroup instance.

cdk.certificate?​

Type : Certificate

If custom domain is enabled, this is the internally created CDK Certificate instance.

cdk.domainName?​

Type : DomainName

If custom domain is enabled, this is the internally created CDK DomainName instance.

cdk.httpApi​

Type : HttpApi

The internally created CDK HttpApi instance.

Methods​

An instance of GraphQLApi has the following methods.

addRoutes​

addRoutes(scope, routes)

Parameters

Adds routes to the Api after it has been created.

api.addRoutes(stack, {
  "GET    /notes/{id}": "src/get.main",
  "PUT    /notes/{id}": "src/update.main",
  "DELETE /notes/{id}": "src/delete.main",
});

attachPermissions​

attachPermissions(permissions)

Parameters

Attaches the given list of permissions to all the routes. This allows the functions to access other AWS resources.

api.attachPermissions(["s3"]);

attachPermissionsToRoute​

attachPermissionsToRoute(routeKey, permissions)

Parameters

Attaches the given list of permissions to a specific route. This allows that function to access other AWS resources.

const api = new Api(stack, "Api", {
  routes: {
    "GET    /notes": "src/list.main",
  },
});

api.attachPermissionsToRoute("GET /notes", ["s3"]);

bind​

bind(constructs)

Parameters

  • constructs Array<SSTConstruct>

Binds the given list of resources to all the routes.

api.bind([STRIPE_KEY, bucket]);

bindToRoute​

bindToRoute(routeKey, constructs)

Parameters

  • routeKey string
  • constructs Array<SSTConstruct>

Binds the given list of resources to a specific route.

const api = new Api(stack, "Api", {
  routes: {
    "GET /notes": "src/list.main",
  },
});

api.bindToRoute("GET /notes", [STRIPE_KEY, bucket]);

getConstructMetadata​

getConstructMetadata()

getFunction​

getFunction(routeKey)

Parameters

  • routeKey string

Get the instance of the internally created Function, for a given route key where the routeKey is the key used to define a route. For example, GET /notes.

const api = new Api(stack, "Api", {
  routes: {
    "GET /notes": "src/list.main",
  },
});

const listFunction = api.getFunction("GET /notes");

setCors​

setCors(cors)

Parameters

Binds the given list of resources to a specific route.

const api = new Api(stack, "Api");

api.setCors({
  allowMethods: ["GET"],
});