1,293 reads

How to Set up Custom Domain Names for AppSync

by Yan CuiSeptember 30th, 2020

Too Long; Didn't Read

API Gateway supports AppSync but you can’t do with AppSync out-of-the-box yet is custom domain names. You can set up an HTTP proxy that routes traffic to the AppSync API, and then configure a custom domain name in API Gateway. This approach takes more work to set up and incurs higher cost and latency (compared to using CloudFront) because every request has to go through API Gateway so you can't easily declare an API Gateway without any Lambda functions.

Companies Mentioned

featured image - How to Set up Custom Domain Names for AppSync

One thing that API Gateway supports but you can’t do with AppSync out-of-the-box yet is custom domain names.

Your shiny new AppSync API is available at

XYZ.appsync-api.us-east-1.amazonaws.com/graphql

, but you really want people to use your own domain instead because

dev.example.com/graphql

is much more memorable and informative.

In this post, let’s look at two ways you can do this.

I previously wrote about five reasons you should consider AppSync over API Gateway. Check out the article here.

1. CloudFront

This is my preferred way. It’s easy to set up and cheap to run.

Assuming your AppSync API resource is called

GraphQlApi

(if you use the serverless-appsync-plugin with the Serverless framework, then this is the logical id it’ll use). This is the CloudFormation resource you need to configure to route traffic to the AppSync API.

AppSyncDistribution:
  Type: AWS::CloudFront::Distribution
  Properties:
    DistributionConfig:
      Origins:
        - Id: AppSync
          DomainName:
            Fn::Select:
              - '2'
              - Fn::Split:
                  - "/"
                  - Fn::GetAtt:
                      - GraphQlApi
                      - GraphQLUrl
          CustomOriginConfig:
            HTTPPort: 80
            HTTPSPort: 443
            OriginProtocolPolicy: https-only
            OriginSSLProtocols:
              - TLSv1
              - TLSv1.1
              - TLSv1.2
          OriginPath: ''
      Enabled: true
      HttpVersion: http2
      Comment: CloudFront distribution for the Patient AppSync API
      Aliases:
        - <INSERT DOMAIN NAME HERE, e.g. dev.example.com>
      PriceClass: PriceClass_100
      DefaultCacheBehavior:
        AllowedMethods:
          - HEAD
          - OPTIONS
          - GET
          - DELETE
          - POST
          - PUT
          - PATCH
        CachedMethods:
          - HEAD
          - OPTIONS
          - GET
        ForwardedValues:
          QueryString: true
          Headers:
            - x-api-key
            - Authorization
          Cookies:
            Forward: all
        MinTTL: 0
        DefaultTTL: 0
        TargetOriginId: AppSync
        ViewerProtocolPolicy: redirect-to-https
        Compress: true
      CustomErrorResponses: []
      ViewerCertificate:
        AcmCertificateArn: <INSERT ARN HERE>
        SslSupportMethod: sni-only

If you’re using the Serverless framework, then you should also check out the serverless-appsync-cloudfront plugin. It can make things a lot easier for you. However, at the time of writing, it makes assumptions about the logical Id of the AppSync API (it expects

GraphQlApi

) as it’s intended to used alongside the aforementioned

serverless-appsync-plugin

2. API Gateway

Another way you can do this is through API Gateway. You can set up an HTTP proxy that routes traffic to the AppSync API, and then configure a custom domain name in API Gateway.

Compared to using CloudFront, this approach takes more work to set up and incurs higher cost and latency (compared to using CloudFront) because every request has to go through API Gateway.

If you’re using the Serverless framework, then another stumbling block is that you can’t easily declare an API Gateway without any Lambda functions. Luckily, you can work around this by bringing SAM’s macro

AWS::Serverless-2016–10–31

into the

serverless.yml

like in this post.

This lets you configure API Gateway using SAM’s AWS::Serverless::Api resource type.

ApiGateway:
  Type: AWS::Serverless::Api
  Properties:
    Name: AppSyncApiProxy
    StageName: dev
    OpenApiVersion: "3.0.1"
    DefinitionBody:
      openapi: "3.0.1"
      paths:
        /{proxy+}:
          "x-amazon-apigateway-any-method":
            consumes:
              - "application/json"
            produces:
              - "application/json"
            parameters:
              - name: proxy
                in: path
                required: true
                type: string
            x-amazon-apigateway-integration:
              uri: 
                Fn::Join:
                  - ''
                  - - 'https://'
                    - Fn::Select:
                        - '2'
                        - Fn::Split:
                            - "/"
                            - Fn::GetAtt:
                                - GraphQlApi
                                - GraphQLUrl
                    - '/{proxy}'
              passthroughBehavior: when_no_match
              httpMethod: ANY
              type: http_proxy                  
              requestParameters:
                integration.request.path.proxy : method.request.path.proxy
    EndpointConfiguration: REGIONAL

ApiGatewayDomainName:
  Type: AWS::ApiGateway::DomainName
  Properties:
    DomainName: <INSERT DOMAIN NAME>
    EndpointConfiguration:
      Types:
        - REGIONAL
    RegionalCertificateArn: <INSERT ARN HERE>

ApiGatewayBasePathMapping:
  Type: AWS::ApiGateway::BasePathMapping
  DependsOn:
    - ApiGatewayDomainName
  Properties:
    DomainName: <INSERT DOMAIN NAME>
    RestApiId: !Ref ApiGateway
    Stage: !Ref ApiGateway.Stage