docs: Clarify the differences between API Gateway versions

API Gateway's REST APIs and HTTP APIs are confusing. As we move towards HTTP APIs by default, we want to clarify the differences between the two.
serverless · Sep 13, 2021 · 1dfad8f · 1dfad8f
1 parent 171897d
commit 1dfad8f
Show file tree

Hide file tree

Showing 2 changed files with 67 additions and 48 deletions.
diff --git a/docs/providers/aws/events/apigateway.md b/docs/providers/aws/events/apigateway.md
@@ -12,51 +12,63 @@ layout: Doc
 
 <!-- DOCS-SITE-LINK:END -->
 
-# API Gateway
-
-- [API Gateway](#api-gateway)
-  - [Lambda Proxy Integration](#lambda-proxy-integration)
-    - [Simple HTTP Endpoint](#simple-http-endpoint)
-    - [Example "LAMBDA-PROXY" event (default)](#example-lambda-proxy-event-default)
-    - [HTTP Endpoint with Extended Options](#http-endpoint-with-extended-options)
-    - [Enabling CORS](#enabling-cors)
-    - [HTTP Endpoints with `AWS_IAM` Authorizers](#http-endpoints-with-aws_iam-authorizers)
-    - [HTTP Endpoints with Custom Authorizers](#http-endpoints-with-custom-authorizers)
-    - [HTTP Endpoints with `operationId`](#http-endpoints-with-operationId)
-    - [Catching Exceptions In Your Lambda Function](#catching-exceptions-in-your-lambda-function)
-    - [Setting API keys for your Rest API](#setting-api-keys-for-your-rest-api)
-    - [Configuring endpoint types](#configuring-endpoint-types)
-    - [Request Parameters](#request-parameters)
-    - [Request Schema Validators](#request-schema-validators)
-    - [Setting source of API key for metering requests](#setting-source-of-api-key-for-metering-requests)
-  - [Lambda Integration](#lambda-integration)
-    - [Example "LAMBDA" event (before customization)](#example-lambda-event-before-customization)
-    - [Request templates](#request-templates)
-      - [Default Request Templates](#default-request-templates)
-      - [Custom Request Templates](#custom-request-templates)
-      - [Pass Through Behavior](#pass-through-behavior)
-    - [Responses](#responses)
-      - [Custom Response Headers](#custom-response-headers)
-      - [Custom Response Templates](#custom-response-templates)
-    - [Status Codes](#status-codes)
-      - [Available Status Codes](#available-status-codes)
-      - [Using Status Codes](#using-status-codes)
-      - [Custom Status Codes](#custom-status-codes)
-  - [Setting an HTTP Proxy on API Gateway](#setting-an-http-proxy-on-api-gateway)
-  - [Accessing private resources using VPC Link](#accessing-private-resources-using-vpc-link)
-  - [Mock Integration](#mock-integration)
-  - [Share API Gateway and API Resources](#share-api-gateway-and-api-resources)
-    - [Easiest and CI/CD friendly example of using shared API Gateway and API Resources.](#easiest-and-cicd-friendly-example-of-using-shared-api-gateway-and-api-resources)
-    - [Manually Configuring shared API Gateway](#manually-configuring-shared-api-gateway)
-      - [Note while using authorizers with shared API Gateway](#note-while-using-authorizers-with-shared-api-gateway)
-  - [Share Authorizer](#share-authorizer)
-  - [Resource Policy](#resource-policy)
-  - [Compression](#compression)
-  - [Binary Media Types](#binary-media-types)
-  - [Detailed CloudWatch Metrics](#detailed-cloudwatch-metrics)
-  - [AWS X-Ray Tracing](#aws-x-ray-tracing)
-  - [Tags / Stack Tags](#tags--stack-tags)
-  - [Logs](#logs)
+# API Gateway REST API
+
+API Gateway lets you deploy HTTP APIs. It comes [in two versions](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html):
+
+- v1, also called **REST API**
+- v2, also called **HTTP API**, which is faster and cheaper than v1
+
+Despite their confusing name, both versions allow deploying any HTTP API (like REST, GraphQL, etc.). Read the full comparison [in the AWS documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html).
+
+This guide documents using API Gateway **v1 REST API** via the `http` event.
+
+To use API Gateway **v2 HTTP API** instead, follow the [HTTP API guide](http-api.md).
+
+Summary:
+
+- [Lambda Proxy Integration](#lambda-proxy-integration)
+  - [Simple HTTP Endpoint](#simple-http-endpoint)
+  - [Example "LAMBDA-PROXY" event (default)](#example-lambda-proxy-event-default)
+  - [HTTP Endpoint with Extended Options](#http-endpoint-with-extended-options)
+  - [Enabling CORS](#enabling-cors)
+  - [HTTP Endpoints with `AWS_IAM` Authorizers](#http-endpoints-with-aws_iam-authorizers)
+  - [HTTP Endpoints with Custom Authorizers](#http-endpoints-with-custom-authorizers)
+  - [HTTP Endpoints with `operationId`](#http-endpoints-with-operationId)
+  - [Catching Exceptions In Your Lambda Function](#catching-exceptions-in-your-lambda-function)
+  - [Setting API keys for your Rest API](#setting-api-keys-for-your-rest-api)
+  - [Configuring endpoint types](#configuring-endpoint-types)
+  - [Request Parameters](#request-parameters)
+  - [Request Schema Validators](#request-schema-validators)
+  - [Setting source of API key for metering requests](#setting-source-of-api-key-for-metering-requests)
+- [Lambda Integration](#lambda-integration)
+  - [Example "LAMBDA" event (before customization)](#example-lambda-event-before-customization)
+  - [Request templates](#request-templates)
+    - [Default Request Templates](#default-request-templates)
+    - [Custom Request Templates](#custom-request-templates)
+    - [Pass Through Behavior](#pass-through-behavior)
+  - [Responses](#responses)
+    - [Custom Response Headers](#custom-response-headers)
+    - [Custom Response Templates](#custom-response-templates)
+  - [Status Codes](#status-codes)
+    - [Available Status Codes](#available-status-codes)
+    - [Using Status Codes](#using-status-codes)
+    - [Custom Status Codes](#custom-status-codes)
+- [Setting an HTTP Proxy on API Gateway](#setting-an-http-proxy-on-api-gateway)
+- [Accessing private resources using VPC Link](#accessing-private-resources-using-vpc-link)
+- [Mock Integration](#mock-integration)
+- [Share API Gateway and API Resources](#share-api-gateway-and-api-resources)
+  - [Easiest and CI/CD friendly example of using shared API Gateway and API Resources.](#easiest-and-cicd-friendly-example-of-using-shared-api-gateway-and-api-resources)
+  - [Manually Configuring shared API Gateway](#manually-configuring-shared-api-gateway)
+    - [Note while using authorizers with shared API Gateway](#note-while-using-authorizers-with-shared-api-gateway)
+- [Share Authorizer](#share-authorizer)
+- [Resource Policy](#resource-policy)
+- [Compression](#compression)
+- [Binary Media Types](#binary-media-types)
+- [Detailed CloudWatch Metrics](#detailed-cloudwatch-metrics)
+- [AWS X-Ray Tracing](#aws-x-ray-tracing)
+- [Tags / Stack Tags](#tags--stack-tags)
+- [Logs](#logs)
 
 _Are you looking for tutorials on using API Gateway? Check out the following resources:_
 

diff --git a/docs/providers/aws/events/http-api.md b/docs/providers/aws/events/http-api.md
@@ -12,11 +12,18 @@ layout: Doc
 
 <!-- DOCS-SITE-LINK:END -->
 
-# HTTP API
+# API Gateway HTTP API
 
-HTTP APIs are a special flavored [API Gateway](https://aws.amazon.com/api-gateway/) implementation which offer more features and improved performance. They have some benefits and drawbacks compared to the traditional API Gateway REST APIs. Read the differences in the [AWS Documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html).
+API Gateway lets you deploy HTTP APIs. It comes [in two versions](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html):
 
-The Serverless Framework makes it possible to setup [API Gateway](https://aws.amazon.com/api-gateway/) HTTP APIs via the `httpApi` event.
+- v1, also called **REST API**
+- v2, also called **HTTP API**, which is faster and cheaper than v1
+
+Despite their confusing name, both versions allow deploying any HTTP API (like REST, GraphQL, etc.). Read the full comparison [in the AWS documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html).
+
+This guide documents using API Gateway **v2 HTTP API** via the `httpApi` event.
+
+To use API Gateway **v1 REST API** instead, follow the [API Gateway REST API guide](apigateway.md).
 
 ## Event Definition