API Gateway (AGW) is a crucial AWS service for developers who want to build a serverless system with a public API. In late 2019, AWS announced version 2 of its API Gateway at its annual re:invent conference in Las Vegas.
The second version isn’t a replacement for the first, but an addition. While the first version comes with fully fledged REST features, the second version focuses on basic HTTP and WebSocket interactions.
These version numbers relate mainly to the configuration APIs you use to set up AGW, not to the REST/HTTP APIs you build with it. For example, you would use the
apigateway AWS CLI command to create a REST API and the
apigatewayv2 command to create an HTTP API.
Comparing REST and HTTP APIs
This article will focus on REST and HTTP APIs and not on the WebSocket protocol, because it isn’t available in version 1.
Since AWS uses “REST API” to refer to version 1 and “HTTP API” to refer to version 2 of the AGW, this article will do that too.
The first issue is pricing, because in serverless architectures, AGW often has a notoriously high price point. At $1 per 300 million requests a month, the new HTTP API is significantly cheaper than the old REST API, which costs $3.50 for the same request volume.
While these prices vary a bit from region to region, this makes an HTTP API almost 70 percent cheaper.
As with all cloud-based services, this price tag shouldn’t be taken at face value. The REST API may be more expensive per request, but it also provides many more features than the HTTP API.
These features could lower the TCO dramatically, because work you don’t have to do yourself is money saved. But if you don’t need them, you can go with the HTTP API and save money.
Latency is a crucial factor when building an API, and an HTTP API comes with 50 percent of the latency of a comparable REST API. This is largely because a REST API provides additional features. However, if you don’t need these features and are mostly concerned about speed, go with an HTTP API.
Keep in mind that a REST API allows edge-optimized deployments, which lowers latency related to distance from your clients. If global deployments are a concern, you may very well want to trade 50 percent latency for an edge deployment.
Also, the REST API comes with integrated caching, which lowers latency too. If your API has good caching behavior, it may make sense to use a REST API so that you won’t have to implement a cache on your own.
The HTTP API allows authentication only with Native OpenID Connect or Cognito as a JWT issuer because it doesn’t have the special authentication features of the REST API. As mentioned above, the HTTP API is more basic.
The REST API has better integrations into the AWS ecosystem. It allows IAM, Cognito, and custom Lambda authentication, if needed. The IAM integration in particular can be useful if you want to build a private API for internal use.
However, if you want to roll your own authentication anyway, you’re better off with an HTTP API.
The HTTP API can integrate with backend services only via Lambda proxy integration or HTTP proxy integration, while the REST API can also integrate directly with AWS services and Mocks.
Again, this makes REST APIs better integrated into the AWS ecosystem. The direct AWS access allows for the use of VTL templates instead of custom Lambda glue functions for the integrations. Once you leave the Lambda free tier, every execution adds to the cost per request of your API. VTL templates are more limited than Lambda functions, but they are executed inside AGW and don’t cost extra money.
As noted, the HTTP API comes with the basics. For API management, this means only custom domains will be configurable.
REST API, on the other hand, provides usage plans and out-of-the-box API Key management, which again, can be quite a time saver if you want to build an API-backed software as a service business and lower your TCO significantly.
The REST API comes with features like caching, request transformation, request and response validation, and test invocations, which can be tiresome to set up.
The HTTP API doesn’t include the REST API’s features but has tricks of its own. It comes with a better CORS support, so you don’t have to add headers manually for every response, and it has automatic deployment and default stage and route, so at least the basics are taken care of.
For security, only the REST API comes with built-in features that simplify your work: client certificates, AWS WAF integration, and resource policies.
If you use the HTTP API, you’ll have to get your API secured without any help from AWS. If you have security concerns or want to manage security on your own, HTTP API can help save you time because you won’t have to deal with the additional complexity of a REST API.
The REST API comes with three API types: regional, edge-optimized, and private.
Edge-optimized APIs can be a crucial feature if you want to deploy your API globally to reduce latency related to geographical distance from your customers. This kind of latency can sometimes be so high that the 50 percent latency saved with an HTTP API won’t cut it anymore.
The HTTP API can only be deployed as a regional API.
When creating an HTTP API you can send access logs to Amazon CloudWatch Logs and use Amazon CloudWatch metrics. With the REST API you can do this too, but you can also send its access logs to Amazon Kinesis Data Firehose, use execution logs, and get access to AWS X-Ray.
This makes the HTTP API monitoring abilities of AWS more limited. If that is a problem, you can use third-party monitoring services like Thundra to get detailed end-to-end insights on your API.
How Should You Build Your API?
HTTP API is basically a stripped-down REST API with fewer features but easier setup, lower pricing, lower latency, and better CORS and JWT support.
If you want to go all in on AWS with good integrations and extended API Gateway features, and if you don’t mind the extra work in CloudFormation, REST API is the way to go. Also, if you have to deploy your API globally, edge-optimized deployment could be the deal breaker here.
If you use a framework like Express or Sinatra that sets up its routes with code, you’re better off with HTTP API. There are many REST API features that you won’t need here, and it could become quite an effort to bend REST API to allow such behavior.
If monitoring is a concern for you, you could feel the need to use the REST API even if it doesn’t suit your other requirements. Luckily, though, third-party monitoring services like Thundra can provide you with extensive insights about your API so you don’t have to rely on AWS monitoring alone.
We haven’t talked about WebSockets here, but since it’s only supported in version 2 of AGW, it’s a case of Hobson’s choice.