feat: implement initial version of the module

README.md

@@ -1,2 +1,75 @@
-# Library project layout
-This is the boilerplate for a library package
+# SkyLeague `aws-rest-api` - AWS API Gateway REST API simplified
+
+This module simplifies the deployment of AWS API Gateway REST API (v1) by consolidating all the neccessary infrastructure into this module. It leverages the capability of the REST API to deploy using the [`body`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_rest_api#body) argument, rather than deploying all the resources/methods/integrations separately. This makes for a very dynamic deployment without the hassle of maintaining the sub-resource <-> parent relations between all the path parts (for examples, see the [`aws_api_gateway_integration`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration) docs of Terraform).
+
+In addition, it simplifies the integration of AWS Lambda by providing a standardized syntax to integrate AWS Lambda using the `AWS_PROXY` integration, as well as creating all the neccesary permissions for the API to invoke the Lambda functionss that are integrated with it.
+
+## Dependencies
+
+In order to deploy this Terraform module, you need a working `node` installation available during the deployment, with accompanying `npx` executable (usually present when `node` is installed). `node` is used in order to dynamically generate the OpenAPI `body` that defines the integrations with the REST API. The `ajv` package is a required dependency for validating the input of the generation script. This can be installed in the project `node_modules` (it likely is if you're using Javascript/Typescript in your toolchain), or as a global `npm` package.
+
+## Usage
+
+```terraform
+module "api" {
+  source = "git@github.com:skyleague/aws-rest-api.git?ref=v1.0.0"
+
+  name   = "my-awesome-api"
+
+  definition = jsonencode({
+    "/v1/hello-world" = {
+      "GET" = {
+        # This also supports the aws_lambda_alias type
+        lambda = aws_lambda_function.hello_world
+      }
+    }
+  })
+}
+```
+
+## Options
+
+For a complete reference of all variables, have a look at the descriptions in [`variables.tf`](./variables.tf).
+
+## Advanced options
+
+Besides the `definition`, the module allows you to pass an `extensions` argument. This argument will get augmented to the top-level of the OpenAPI `body` in the creation of the REST API. The `extensions` argument allows full configuration using the [API Gateway extensions to OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html). As opposed to top-level extensions, the endpoint-level extensions can be configured at the same level as the `lambda` configuration. See the example below to get a glimpse of how this would work.
+
+```hcl
+module "api" {
+  source = "git@github.com:skyleague/aws-rest-api.git?ref=v1.0.0"
+
+  name   = "my-awesome-api"
+
+  definition = jsonencode({
+    "/v1/hello-world" = {
+      "GET" = {
+        parameters = [{
+          name     = "name",
+          in       = "query",
+          required = true,
+          type     = "string"
+        }]
+        "x-amazon-apigateway-integration" = {
+          cacheKeyParameters = ["method.request.querystring.name"]
+        }
+        lambda = aws_lambda_function.hello_world
+      }
+    }
+  })
+
+  extensions = jsonencode({
+    "x-amazon-apigateway-binary-media-types": [ "application/octet", "image/jpeg" ]
+  })
+}
+```
+
+## Future additions
+
+This is the initial release of the module, with a very minimal set of standardized functionality. Most other functionality can already be achieved through [API Gateway extensions to OpenAPI](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html), even the ones mentioned for standardization below. We plan on standardizing more integrations, so feel free to leave suggestions! Candidates include:
+
+- Authorizers (custom, apiKey, etc)
+- Direct S3 integrations
+- Standardized `MOCK` integrations
+- Standardized `HTTP_PROXY` integrations
+- ... **Your suggestions!**

iam.tf

@@ -0,0 +1,20 @@
+resource "aws_cloudformation_stack" "lambda_permissions" {
+  name = "${var.name}-lambda-permissions-${aws_api_gateway_rest_api.this.id}"
+  template_body = jsonencode({
+    Resources = merge([
+      for urlPath, config in local.definition : {
+        for httpMethod, definition in config : "AllowExecutionFromAPIGateway${substr(sha256("${upper(httpMethod)} ${urlPath}  "), 0, 8)}" => {
+          Type = "AWS::Lambda::Permission"
+          Properties = {
+            FunctionName = definition.lambda.function_name
+            Action       = "lambda:InvokeFunction"
+            Principal    = "apigateway.amazonaws.com"
+
+            #   # More: http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html
+            SourceArn = "arn:aws:execute-api:${data.aws_region.current.name}:${data.aws_caller_identity.current.account_id}:${aws_api_gateway_rest_api.this.id}/*/${upper(httpMethod)}${urlPath}"
+          }
+        }
+      }
+    ]...)
+  })
+}

logs.tf

@@ -0,0 +1,29 @@
+resource "aws_cloudwatch_log_group" "execution" {
+  for_each = {
+    for stage, config in {
+      for stage in local.log_stages : stage => lookup(var.log_settings_override, stage, {
+        disabled          = var.log_creation_disabled
+        retention_in_days = var.log_retention_in_days
+        kms_key_id        = var.log_kms_key_id
+      })
+    } : stage => config if !config.disabled
+  }
+  name              = "API-Gateway-Execution-Logs_${aws_api_gateway_rest_api.this.id}/${each.key}"
+  retention_in_days = each.value.retention_in_days
+  kms_key_id        = each.value.kms_key_id
+}
+
+resource "aws_cloudwatch_log_group" "access" {
+  for_each = {
+    for stage, config in {
+      for stage in local.log_stages : stage => lookup(var.log_settings_override, stage, {
+        disabled          = var.log_creation_disabled
+        retention_in_days = var.log_retention_in_days
+        kms_key_id        = var.log_kms_key_id
+      })
+    } : stage => config if !config.disabled
+  }
+  name              = "API-Gateway-Access-Logs_${aws_api_gateway_rest_api.this.id}/${each.key}"
+  retention_in_days = each.value.retention_in_days
+  kms_key_id        = each.value.kms_key_id
+}

main.tf

@@ -0,0 +1,65 @@
+data "external" "spec" {
+  program = ["npx", "-y", "ts-node", "-T", "--skip-project", "${path.module}/scripts/src/index.ts"]
+
+  query = {
+    definition = jsonencode(local.definition)
+    extensions = var.extensions
+  }
+}
+resource "aws_api_gateway_rest_api" "this" {
+  name        = var.name
+  description = coalesce(var.description, "API for ${var.name}")
+
+  disable_execute_api_endpoint = var.disable_execute_api_endpoint
+  endpoint_configuration {
+    types            = [var.endpoint_type]
+    vpc_endpoint_ids = var.endpoint_type == "PRIVATE" ? var.vpc_endpoint_ids : null
+  }
+
+  body = jsonencode(jsondecode(data.external.spec.result.spec))
+}
+
+resource "aws_api_gateway_method_settings" "this" {
+  for_each = var.disable_global_method_settings ? [] : var.stages
+
+  rest_api_id = aws_api_gateway_rest_api.this.id
+  stage_name  = aws_api_gateway_stage.this[each.key].stage_name
+  method_path = "*/*"
+
+  settings {
+    logging_level      = var.logging_level
+    metrics_enabled    = var.metrics_enabled
+    data_trace_enabled = var.data_trace_enabled
+  }
+}
+
+resource "aws_api_gateway_deployment" "this" {
+  rest_api_id = aws_api_gateway_rest_api.this.id
+
+  triggers = {
+    redeployment = sha1(aws_api_gateway_rest_api.this.body)
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "aws_api_gateway_stage" "this" {
+  for_each      = var.stages
+  deployment_id = aws_api_gateway_deployment.this.id
+  rest_api_id   = aws_api_gateway_rest_api.this.id
+  stage_name    = each.value
+
+  xray_tracing_enabled = var.xray_tracing_enabled
+
+  access_log_settings {
+    destination_arn = aws_cloudwatch_log_group.access[each.key].arn
+    format          = jsonencode(var.custom_access_logs_format)
+  }
+
+  depends_on = [
+    aws_cloudwatch_log_group.execution,
+    aws_cloudformation_stack.lambda_permissions,
+  ]
+}

outputs.tf

@@ -0,0 +1,15 @@
+output "rest_api" {
+  value = aws_api_gateway_rest_api.this
+}
+
+output "stage" {
+  value = aws_api_gateway_stage.this
+}
+
+output "access_log_groups" {
+  value = aws_cloudwatch_log_group.access
+}
+
+output "execution_log_groups" {
+  value = aws_cloudwatch_log_group.execution
+}