Ben's notes

Lambdas and aws: The clear difference between API and HTTP API

Summary: Use HttpApi.

Taxonomy

Probably the most painful aspect of this is that at some point AWS completely gave up on taxonomically separating these two services and basically throughout the documentation they’re referred to using many different conflicting and confusing names. To make sense of this you need to completely ignore the normal (sane) use of the words “http”, “api” or “rest” as they’re purely arbitrary classifiers for amazon. That said, here is the best taxonomic separation I can arrive at:

Type 1: Api

Type 2: HttpApi

Official documentation

  • AWS’ own comparison (warning: basically useless).

  • Authorization methods comparison (e.g. HttpApi does not support IAM but does support OAuth 2.0 where Api does not).

  • See here for clues on the categorization of “Api” and “HttpApi” using the help docs for Cloudformation SAM templates.

Side by side

ApiHttpApi
AKA: Api, REST API, AWS::ApiGateway::RestApi, ServerlessRestApi (Logical Id),AKA: RESTful Api, HTTP API, AWS::Serverless::HttpApi, ServerlessHttpApi (Logical Id), AWS::ApiGatewayV2::Api
Lambda return value: Must return a specific format (source)Will infer correct formatting so can return a string or a Dict, etc (source)
More features, more complicated, harderFewer features, easier, lower cost
Lambda specific docsLambda specific docs
Template resource properties sourceTemplate resource properties (source)
Managed with ApiGateway (v1) sourceManaged with ApiGatewayV2 (which can also create a websocket api) source