API Gateway REST vs. HTTP API: What Are The Differences?

AWS API Gateway is a great technology for managing and securing access to your backend REST APIs. However, AWS currently supports two very different versions of the technology. What are the differences? And which one should you use?

AWS covers the basics of the differences between these two technologies in its documentation. In this article, I plan to dive a little deeper by discussing some of the ways missing features from one version of API Gateway can be supported in the other. I'll also give some proscriptive recommendations around which version to use and when.

V1 vs. V2: Avoiding A Nasty Shock

AWS released the first version of API Gateway in 2015 with support for REST APIs. Over the next several years, AWS added numerous features to its REST API support. These included support for authentication via Cognito user pools, exposing private APIs publicly via VpcLink, and canary deployment support, among many others.

Then in 2019, AWS announced that, based on customer feedback, it had developed a new version of API Gateway. This V2 version included support for "HTTP APIs" (effectively REST APIs) as well as WebSocket APIs. A major goal of the change, AWS said, was to simplify the API Gateway model and make it easier to develop and deploy new APIs.

However, Amazon sowed a lot of confusion with this "new" API Gateway. First off, "HTTP API" is something of an odd naming, given that REST is a framework built on top of the HTTP protocol. I'm at a loss to understand why AWS chose a naming convention that makes them sound like diametric opposites.

Second, the name obfuscates that these are two separate versions of the same technology. This only really becomes clear if you look in one of two places:

• CloudFormation syntax, where REST API and HTTP API syntax have separate namespaces (AWS::ApiGateway and AWS::ApiGatewayV2).
• The AWS Console, where creating a REST API versus an HTTP API gives you two completely separate user experiences.

Above are screenshots of the REST API (first image) and the HTTP API (second image) user interface. As you can see, there's quite a change between V1 and V2. The changes extend, not just to UI organization, but to what features are available - and even down to the price and performance of each system.

In other words, before deciding which version of API Gateway to use, you should understand the differences between V1 and V2 in detail. And when you're researching information on the Web, be careful to identify whether the feature you're reading about is supported in REST APIs, HTTP APIs, or both.

Performance and Price Differences

The major difference between REST APIs and HTTP APIs are in performance and price. In short, HTTP APIs are the winner in both.

Both REST APIs and HTTP APIs only charge for the number of requests actually made plus data transferred out of AWS. However, the difference in pricing is steep. REST APIs will run you USD $3.50 per one million requests plus charges for data transferred out. By contrast, HTTP APIs cost a mere $1.00 per request for the first million requests and then $0.90 per million requests after that. That's a whopping 71% price differential.

On top of that, AWS says that V2 HTTP APIs contain significant performance improvements over their V1 REST brethren. Andreas Wittig at Cloudonaut ran some numbers and found a 14 to 16% improvement in latency in HTTP APIs compared to REST APIs.

As Andreas notes, the latency differential isn't that great. And odds are most of it will be wiped out by dependencies on other components, such as your database. So HTTP APIs are a clear winner in price and a small winner in performance.

Features in REST APIs (But Not in HTTP APIs)

So HTTP APIs are a clear winner when it comes to pricing. But, as I've noted before, price isn't everything. You can justify a higher cost if you're getting something in return for it.

Both REST APIs and HTTP APIs have features the others don't. Let's take a look at each, starting with the features in REST APIs that HTTP APIs lack.

Canary Support

Truth be told, my motivation for writing this article was that I wanted to build an API Gateway deployment with canary support. I'd heard that API Gateway supported canaries. Since I'm a big fan of API Gateway and its capabilities, I rushed into coding.

Unfortunately, what I started creating was an HTTP API. Imagine my shock and disappointment when I realized that HTTP APIs have no support for canary deployments! This is strictly a feature of REST APIs that V2 lacks.

One workaround is to incorporate an Application Load Balancer into your architecture. ALBs also support weighted routing, which allows you to implement canary-style deployments. Using an ALB with API Gateway is an established pattern that provides extra security, as you can host your ALB in a private subnet. You can then use private integrations and VPC Link in API Gateway to route API requests to endpoints in this private subnet.

This pattern carries the added benefit of limiting your Docker container's exposure to the Internet. You can host your container completely in a private subnet and expose only those REST endpoints you want made publicly available. For more information on implementing this pattern, see this article on the AWS Web site, which comes complete with an out of the box CloudFormation template.

Another workaround is to use Route 53's weighted routing feature. (AWS has docs on how to do this in the context of blue/green deployments.) In this case, you'd create another stage (e.g., canary) in your API Gateway. You'd then use weighted routing to route a percentage of traffic to the canary stage, gradually shifting over traffic as you verified the new version's performance. This will work but rollout may be slow due to DNS propagation delays.

Web Application Firewall (WAF) Support

AWS's WAF provides an additional level of security for Web apps. Using WAF, you can apply both pre-made and custom traffic security rules that filter out bots and known exploit vectors. WAF can both keep your application more secure as well as reduce illegitimate, bandwidth-wasting traffic.

API Gateway supports WAF. That is, if you use the REST API. HTTP APIs do not currently support WAF and there's no indication when they might.

If you use the architecture I mention above, you can work around this by turning on WAF on your private Application Load Balancer. ALB supports WAF, which means you can get the benefits of WAF while still enjoying the lower cost and higher performance of HTTP APIs.

Support for AWS X-Ray

X-Ray is AWS's service to add tracing and debugging instrumentation to your code. With X-Ray, you can monitor code and service performance, report errors, and troubleshoot the root cause of issues affecting your callers.

REST APIs have check-button support for adding X-Ray to your API Gateway calls. Sadly, as of this writing, this feature doesn't exist in HTTP APIs.

For teams that use their one home-brewed tracing option or a commercial one like New Relic, this won't be a huge deal. And others can still use X-Ray directly from their code through their programming language's AWS SDK or via the AWS CLI. So, while this is a nice-to-have, it's not necessarily a deal breaker.

Features in REST APIs (But Not in HTTP APIs)

Better Programmatic Model

The programmatic model is one area where HTTP APIs shine. One of AWS's avowed motivations in creating HTTP APIs was that the REST API was too complicated. HTTP APIs use a simplified programming model and a new and improved user interface in the console.

Additionally, HTTP APIs support several ease of use dev features that REST APIs don't, including direct support for CORS configuration, automatic deployments, and a default stage and route. However, REST APIs do support a couple of dev features, such as request body transformation, that aren't directly supported as of this writing in HTTP APIs.

However, REST APIs make development easier in one crucial way: they support importing API definitions from OpenAPI definitions supported by Swagger and other API definition/documentation tools. HTTP APIs can only export to OpenAPI.

Private Integrations

Private integrations allow API Gateway to expose resources hosted in a private VPC. Using a private integration, you can host your API sources (e.g., Docker containers) inside a private subnet while exposing only the endpoints you want to expose publicly through API Gateway. This results in enhanced security.

HTTP APIs contain full-fledged support for Application Load Balancers, Network Load Balancers, and AWS Cloud Map. Support is enabled via VPC Link, which allows you to create a route from your API Gateway to a private subnet. VPC Link is easy to configure and assign in both the console and in CloudFormation. (You can find a working CloudFormation example here.)

REST APIs support only Network Load Balancers. Additionally, the configuration isn't nearly as straightforward as it is with VPC Link.

Private integrations shouldn't be confused with private APIs. With private APIs, you can use API Gateway to define an API that's only available via a VPC. Calls to the API stay within the VPC and never route through the public Internet. Only REST APIs support private APIs.

Native OpenID Connect / OAuth 2.0

Finally, HTTP APIs have native support for OpenID Connect and OAuth 2.0. This is the one authentication framework that REST APIs don't natively support.

It's certainly possible to implement your own OAuth 2.0 support in REST APIs. But this is a heavier lift than just using HTTP API's native support.

Which to Use?

There are a few other feature differences I didn't cover here. It's best to familiarize yourself with the documentation and see what you would get - and what you'd miss - by picking one over the other. To make things easier, here's a quick run-down in table format:

As you can see, HTTP APIs have some catching up to do in terms of feature support. On the other hand, HTTP APIs are drastically more economical, performant, and easy to use.

In my view, you may choose to go with REST APIs if they choose some critical features that will make administration easier and reduce time to market (e.g., OpenAPI import). However, the overall improvements in HTTP APIs make them the default choice for most projects. You can directly implement most of the features unique to REST APIs without great effort. Plus, you'll get the benefit of future usability, price, and performance improvements as AWS continues investing in this new service.

Header image credit: Unsplash