Skip to main content

GraphQLApi

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.

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 : "iam" | "none" | Omit<string, "iam" | "none">

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,
}],
}
});

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

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"]);

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");