Introduction

It's been awhile since AWS released HTTP API or API Gateway v2.

Since its release Serverless Guru, has been helping companies move from API GW v1 to API GW v2 and we've learned a few things in the process.

This article will go over some tips that we've learned while helping on these migrations in the past.

Migration tip #1, API GW v1 to v2

HTTP APIs (API GW v2) with #lambda proxy integration put out different events than the API GW REST (API GW v1)

If migrating code from API GW v1, set 1.0 as your event payload, Serverless Framework also supports this.

Migration tip #2, API GW v1 to v2

Your IAC is going to dramatically change.. when defining a shared API Gateway HTTP API you will need to change all raw CloudFormation from v1 to v2 resources..

They have different options and are not compatible, v1 to v2 from my experience.

Migration tip #3, API GW v1 to v2

If using @goserverless to share a single API Gateway HTTP API you will need to replace apiGateway with httpApi and change how you add auth to each lambda

More information, here.

Migration tip #4, API GW v1 to v2

HTTP APIs (API GW v2) authorizers introduce new language like “Audience” and “Issuer” and setting up Cognito User Pool auth is much less straight forward.

Here is a helpful article from Sander Knape.

The article goes over what an HTTP API would look like defined in AWS CloudFormation

Migration tip #5, API GW v1 to v2

Custom domain issues, requiring modification for v2.

“Mixing of REST APIs and HTTP APIs on the same domain name can only be accomplished through API Gateway’s V2 DomainName interface” - AWS Docs

This is going to require adding an additional IAC resource linked above which works with API GW v2.

Migration tip #6, API GW v1 to v2

The AWS Console view is much different and will not be immediately intuitive.

• “Integrations” — where you tell your route what it should do
• “Authorization” — where your JWT authorizer would show up

With API Gateway v1, you can see the UI we've been accustomed to for the past few years and all though, personally I'm more comfortable with this view, training people on how to navigate and understand API Gateway v1 has been challenging in the past.

With API Gateway v2, you can see that AWS has put a lot of effort into helping categorize different functionality which over the long run will be come intuitive and make v2 seem overly complex.

A key thing to point out with "Integrations" is it's now more clear that you can do more than simply point API Gateway to a lambda function or to another domain.

Migration tip #7, API GW v1 to v2

You can take out the code in your AWS lambda functions which would send back an “Access-Control-Allow-Origin”, “Access-Control-Allow-Methods”, “Access-Control-Allow-Headers”.

V1:

  
  return {
    statusCode: 200,
    body: JSON.stringify({...}),
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "*",
      "Access-Control-Allow-Headers": "*"
    }
  }
  

V2:

  
  return {
    statusCode: 200,
    body: JSON.stringify({...})
  }
  

Helps clean up code and prevent one of the most common issues with new serverless developers where they forget to add the headers and see issues when finally integrating their backend with their frontend.

Migration tip #8, API GW v1 to v2

Better control of throttling, but from my understanding you can’t automate this with CloudFormation and need to add AWS CLI or AWS SDK commands in to handle this, not supported via AWS console either.

I've included a screenshot of the AWS documentation which shows the field names for "RouteSettings" where you can configure throttling for your API GW v2 API.

Conclusion

Alright so with that last tip, this article is coming to a close.

I hope that you found this insightful into some quick things to be aware of when considering migrating from API GW v1 to v2.

If you or your company has any questions about how to make this kind of migration or are looking to hire some consultants to streamline the process.

You can fill out our form below and we will setup a call.

Thank you :)