Belajar Floci - API Gateway Emulation (v1 & v2)

#Pendahuluan

Trio serverless lengkapnya: API Gateway sebagai pintu masuk HTTP → Lambda → layanan data. Tanpa emulasi API Gateway, developer serverless terpaksa deploy ke cloud hanya untuk menguji satu endpoint — justru bagian yang paling sering berubah saat development.

Floci mendukung dua generasi API Gateway sekaligus: REST API (v1) yang kaya fitur, dan HTTP API (v2) yang lebih murah dan cepat. Episode ini membedah keduanya.

#Fitur

#REST API (v1)

Generasi pertama dengan konsep resource/method/stage yang eksplisit:

API_ID=$(aws --endpoint-url=http://localhost:4566 apigateway create-rest-api \
  --name svc-orders --query id --output text)
 
ROOT=$(aws --endpoint-url=http://localhost:4566 apigateway get-resources \
  --rest-api-id "$API_ID" --query 'items[0].id' --output text)
RES=$(aws --endpoint-url=http://localhost:4566 apigateway create-resource \
  --rest-api-id "$API_ID" --parent-id "$ROOT" --path-part orders --query id --output text)
 
aws --endpoint-url=http://localhost:4566 apigateway put-method \
  --rest-api-id "$API_ID" --resource-id "$RES" --http-method GET --authorization-type NONE
 
aws --endpoint-url=http://localhost:4566 apigateway put-integration \
  --rest-api-id "$API_ID" --resource-id "$RES" --http-method GET \
  --type AWS_PROXY --integration-http-method POST \
  --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:000000000000:function:hello/invocations

Fitur v1 yang ditiru meliputi routing berparameter (/orders/{id}), stage deployment (/dev, /prod), hingga custom domain lokal — berguna menguji app yang sensitif terhadap host header.

#HTTP API (v2) — Proxy Integration ke Lambda

Generasi kedua jauh lebih ringkas; payload format 2.0 adalah default aplikasi serverless modern:

aws --endpoint-url=http://localhost:4566 apigatewayv2 create-api \
  --name svc-orders-v2 \
  --protocol-type HTTP \
  --target arn:aws:lambda:us-east-1:000000000000:function:hello

Satu perintah: semua route diteruskan ke Lambda dengan event format 2.0 (requestContext.http.method, rawPath, dst). Routing eksplisit juga bisa via create-route dengan key seperti GET /orders/{id}.

Perbedaan penting yang harus dipahami aplikasi kalian:

Kode handler yang membaca event.path (v1) akan error di v2 yang memakai event.rawPath — inilah jenis bug parity yang uji lokal menangkap lebih awal.

#Praktik

Target outline: ekspos microservice via API Gateway floci + uji kontrak endpoint.

set -euo pipefail
export AWS_ENDPOINT_URL=http://localhost:4566
 
# fungsi backend sederhana
mkdir -p api && cat > api/handler.py <<'EOF'
def handler(event, context):
    method = event["requestContext"]["http"]["method"]
    path = event["rawPath"]
    if method == "POST" and path == "/orders":
        return {"statusCode": 201,
                "body": '{"order_id":"ORD-9","status":"created"}'}
    return {"statusCode": 404, "body": '{"error":"not found"}'}
EOF
(cd api && zip -q ../api.zip handler.py)
aws lambda create-function --function-name orders-api \
  --runtime python3.12 --handler handler.handler \
  --zip-file fileb://api.zip --role arn:aws:iam::000000000000:role/dummy >/dev/null
 
aws apigatewayv2 create-api --name orders-http \
  --protocol-type HTTP \
  --target arn:aws:lambda:us-east-1:000000000000:function:orders-api >/dev/null
echo "API siap di http://localhost:4566"

# kontrak 1: POST /orders -> 201 + JSON body tertentu
curl -s -X POST http://localhost:4566/orders | grep -q '"ORD-9"' && echo "kontrak POST OK"
 
# kontrak 2: path tak dikenal -> 404 konsisten
CODE=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:4566/nope)
[ "$CODE" = "404" ] && echo "kontrak 404 OK"

Simpan kedua curl tersebut sebagai script contract test di repo — jalankan ulang tiap kali handler berubah. Inilah cara tim menjaga API tetap stabil tanpa menyentuh cloud.

#Penutup

Rangkuman episode ini:

• Floci meniru API Gateway v1 (REST: resource/method/stage/custom domain) dan v2 (HTTP API quick-create).
• Perbedaan event format 1.0 vs 2.0 adalah sumber bug klasik — uji lokal menangkapnya gratis.
• Praktik: microservice order diexpos via HTTP API + contract test curl yang bisa masuk CI.

Sisi aplikasi sudah lengkap; episode 9 turun ke layer identitas: IAM, STS & model credentials — kenapa semua credential diterima, dan kenapa kalian tetap disarankan memakai fake profile yang rapi. Sampai jumpa!