🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🧰 धडा 02 — REST विरुद्ध HTTP विरुद्ध WebSocket APIs: front office चे तीन प्रकार

📍 तुम्ही इथे आहात: 12 पैकी धडा 02 · मागे: lesson-01-why-gateway · पुढे: lesson-03-routes-integrations

📦 या ब्रँचमध्ये काय आहे

धडा 01, आणि AWS वर तुम्ही सर्वात आधी करता ती निवड: REST API (पूर्ण साहित्य), HTTP API (हलके आणि स्वस्त) किंवा WebSocket API (उघडी राहणारी line). apigw/demo.py मधले kinds() हे तिन्ही print करते, आणि lab चे office कोणते फक्त-REST भाग वापरते त्यांची तुम्ही यादी करता.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

शाळा तिचे front office तीन प्रकारे बांधू शकते:

पूर्ण office 🏢 (REST API). मोठा desk, अनेक खण: रोजच्या मर्यादेसह visitor passes (API keys आणि usage plans), सूचना फलक (cache), form तपासणारा (request validation), पत्रे नव्याने लिहिणारा clerk (mapping templates), फाटकावरचा पहारेकरी (AWS WAF), आणि फक्त आतल्या visitors साठी एक खाजगी दार.
जलद counter 🪟 (HTTP API). लहान आणि स्वस्त. ते badges तपासते (JWT), एका setting ने browsers ना आत येऊ देते (CORS) आणि पटकन पुढे पाठवते. सूचना फलक नाही, visitor passes नाहीत.
Phone line ☎️ (WebSocket API). Visitor एकदा call करतो आणि line उघडीच राहते. दोन्ही बाजू कधीही बोलू शकतात — marks तयार झाले की शाळा परत call करू शकते.

तुम्हाला लागणारे सगळे खण ज्यात आहेत असे सर्वात लहान office निवडा.

🗺️ आकृती

flowchart TB
    q["❓ what do you need?"]
    rest["🏢 REST API<br/>keys + usage plans · cache · validation<br/>VTL mapping · WAF · private endpoint<br/>~$3.50 per million"]
    http["🪟 HTTP API<br/>JWT authorizer · simple CORS<br/>auto-deploy · Lambda + HTTP proxy<br/>~$1.00 per million"]
    ws["☎️ WebSocket API<br/>$connect · $disconnect · $default<br/>route by a field in the message"]
    q -->|"partners, quotas, caching, WAF"| rest
    q -->|"JWT + Lambda, lower price"| http
    q -->|"server must push: chat, live marks"| ws

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l02

❓ काय

REST API (API Gateway "v1") — पूर्ण साहित्य: API keys आणि usage plans, caching, request validation, mapping templates (VTL मध्ये, म्हणजे Velocity Template Language मध्ये लिहिलेले), AWS WAF, resource policies, आणि तीन endpoint types: edge-optimized, regional आणि private. Authorizers: IAM, Cognito user pools आणि Lambda.
HTTP API (API Gateway "v2", 2019) — हलके: आधीच असलेले JWT authorizers, Lambda authorizers आणि IAM; automatic deployments; एका setting मध्ये CORS; Lambda आणि HTTP proxy integrations, आणि VPC link मधून private integrations. Cache नाही, usage plans नाहीत, request validation नाही, WAF नाही. us-east-1 मध्ये पहिल्या tier साठी अंदाजे किंमत: ~$1.00 प्रति million requests, तर REST साठी ~$3.50 प्रति million.
WebSocket API — दीर्घकाळ टिकणारे, दोन्ही दिशांचे connection. खास routes: $connect, $disconnect आणि $default. $request.body.action सारखे route selection expression प्रत्येक message मधल्या एका field वरून route निवडते. तुमचा back end @connections API मधून messages परत पाठवतो.
Lab REST API चे model बनवते — कारण REST API मध्ये शिकण्यासारखे सर्वात जास्त भाग आहेत.

🤔 का

कारण ही निवड तुमची किंमत ठरवते, आणि कोणती features तुम्ही कधीही चालू करू शकाल तेही. Teams अनेकदा "सुरक्षित राहावे" म्हणून REST निवडतात आणि कधीच न वापरलेल्या features साठी जवळपास साडेतीन पट जास्त पैसे देतात. इतर HTTP निवडतात आणि नंतर त्यांना कळते की partners साठी usage plans किंवा समोर WAF हवा आहे — आणि मग migrate करावे लागते. नावावरून नाही, तर features च्या यादीवरून निर्णय घ्या.

🔧 कसे (या repo मध्ये)

kinds() तिन्ही प्रकार print करते. office() REST-पद्धतीचा API बनवते, आणि apigw/gateway.py मधला प्रत्येक Route REST features flags म्हणून बाळगतो: auth, cache, api_key, schema (request validation) आणि mapping (response mapping). Routes ची यादी केली की lab पूर्ण office चे कोणते खण वापरते ते दिसते.

🧪 करून पाहा

python3 apigw/demo.py kinds
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, _ = office()
for r in gw.routes:
    print(f"{r.method:<5} {r.path:<24} auth={r.auth} cache={r.cache} api_key={r.api_key} schema={'yes' if r.schema else 'no'} mapping={'yes' if r.mapping else 'no'}")
print("stages:", list(gw.stages), "· usage plans:", list(gw.plans))
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

kinds तीन ओळी print करते: REST API the full kit: API keys + usage plans, caching, request validation, mapping templates, WAF, private, HTTP API lean and cheaper: JWT authorizers built in, CORS in one setting, Lambda + HTTP proxy, WebSocket API a phone line that stays open: $connect, $disconnect, routes by a field in the message, मग this lab models a REST API because it shows the most parts.

तुमचा snippet आठ routes print करतो. त्यापैकी तीन फक्त-REST खण वापरतात: GET /students/{id} auth=None cache=True api_key=False schema=no mapping=yes (cache आणि mapping), POST /marks auth=jwt cache=False api_key=False schema=yes mapping=no (validation) आणि GET /partner/students/{id} auth=None cache=False api_key=True schema=no mapping=no (API key). मग stages: ['dev', 'prod'] · usage plans: ['partner-basic']. HTTP API मध्ये cache, validator, mapping किंवा usage plan बसू शकले नसते.

🏁 तुम्ही आत्ताच काय सिद्ध केले

API च्या गरजा वाचून तुम्ही त्याचा प्रकार सांगू शकता: हा शाळेचा API cache, validator, mapping आणि usage plan वापरतो, म्हणून त्याला REST API लागतो. त्या चार गोष्टी नसत्या, तर HTTP API ने तेच काम कमी खर्चात केले असते.

⚠️ नेहमीच्या चुका

साध्या "JWT + Lambda" API साठी सवयीने REST निवडणे — HTTP स्वस्त आणि सोपे आहे
HTTP निवडणे आणि नंतर usage plans, caching किंवा WAF लागणे — आधी features ची यादी ठरवा
एकाच उत्तराच्या request साठी WebSocket वापरणे — साधी request जास्त सोपी आहे
WebSocket (किंवा push service) परत call करू शकत असताना बातमीसाठी दर सेकंदाला polling करणे

🏭 प्रत्यक्ष वापरात

On a real account — तोच students route HTTP API (AWS SAM) म्हणून आणि REST API (AWS SAM) म्हणून, शेजारी शेजारी:

# template.yaml — AWS SAM
Resources:
  StudentsFn:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.12
      Handler: app.handler
      CodeUri: src/
      Events:
        LeanCounter:                       # HTTP API
          Type: HttpApi
          Properties: { Path: /students/{id}, Method: GET }
        FullOffice:                        # REST API
          Type: Api
          Properties: { Path: /students/{id}, Method: GET }

WebSocket API त्याचा route message body वरून निवडतो:

aws apigatewayv2 create-api --name school-live --protocol-type WEBSOCKET \
    --route-selection-expression '$request.body.action'

🏭 Production मध्ये हे का महत्त्वाचे: प्रकार नंतर बदलणे अवघड असते — clients, domains आणि authorizers त्याच्याभोवती बांधलेले असतात. API बनवण्याआधी तुम्हाला लागणारी features लिहून ठेवा (keys? cache? WAF? private?).

⏭️ पुढे

Office निवडले. आता: कोणता desk कोणत्या visitor ला घेतो? Routes आणि integrations.

git checkout lesson-03-routes-integrations

🧰 Lesson 02 — REST vs HTTP vs WebSocket APIs: three kinds of front office

📍 You are here: Lesson 02 of 12 · Previous: lesson-01-why-gateway · Next: lesson-03-routes-integrations

📦 What's in this branch

Lesson 01, plus the choice you make first on AWS: a REST API (the full kit), an HTTP API (lean and cheaper) or a WebSocket API (a line that stays open). kinds() in apigw/demo.py prints the three, and you list which REST-only parts the lab office uses.

🧒 Explain like I'm 5

The school can build its front office in three ways:

The full office 🏢 (REST API). Big desk, many drawers: visitor passes with daily limits (API keys and usage plans), a notice board (cache), a form checker (request validation), a clerk who rewrites letters (mapping templates), a guard at the gate (AWS WAF), and a private door for inside visitors only.
The quick counter 🪟 (HTTP API). Smaller and cheaper. It checks badges (JWT), lets browsers in with one setting (CORS) and forwards fast. No notice board, no visitor passes.
The phone line ☎️ (WebSocket API). The visitor calls once and the line stays open. Both sides can talk at any time — the school can call back when the marks are ready.

Pick the smallest office that has every drawer you need.

🗺️ Diagram

flowchart TB
    q["❓ what do you need?"]
    rest["🏢 REST API<br/>keys + usage plans · cache · validation<br/>VTL mapping · WAF · private endpoint<br/>~$3.50 per million"]
    http["🪟 HTTP API<br/>JWT authorizer · simple CORS<br/>auto-deploy · Lambda + HTTP proxy<br/>~$1.00 per million"]
    ws["☎️ WebSocket API<br/>$connect · $disconnect · $default<br/>route by a field in the message"]
    q -->|"partners, quotas, caching, WAF"| rest
    q -->|"JWT + Lambda, lower price"| http
    q -->|"server must push: chat, live marks"| ws

🗺️ Drawn version + a lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l02

❓ What

REST API (API Gateway "v1") — the full kit: API keys and usage plans, caching, request validation, mapping templates (written in VTL, the Velocity Template Language), AWS WAF, resource policies, and three endpoint types: edge-optimized, regional and private. Authorizers: IAM, Cognito user pools and Lambda.
HTTP API (API Gateway "v2", 2019) — lean: built-in JWT authorizers, Lambda authorizers and IAM; automatic deployments; CORS in one setting; Lambda and HTTP proxy integrations and private integrations through a VPC link. No cache, no usage plans, no request validation, no WAF. Approximate price in us-east-1 for the first tier: ~$1.00 per million requests, against ~$3.50 per million for REST.
WebSocket API — a long-lived, two-way connection. Special routes: $connect, $disconnect and $default. A route selection expression such as $request.body.action picks the route from a field in each message. Your back end sends messages back through the @connections API.
The lab models a REST API — because a REST API has the most parts to learn.

🤔 Why

Because the choice decides your price and which features you can ever turn on. Teams often pick REST "to be safe" and pay about three and a half times more for features they never use. Others pick HTTP and later find they need usage plans for partners or WAF in front — and must migrate. Decide from the feature list, not from the name.

🔧 How (in this repo)

kinds() prints the three kinds. office() builds a REST-style API, and each Route in apigw/gateway.py carries the REST features as flags: auth, cache, api_key, schema (request validation) and mapping (response mapping). Listing the routes shows which drawers of the full office the lab uses.

🧪 Try it

python3 apigw/demo.py kinds
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, _ = office()
for r in gw.routes:
    print(f"{r.method:<5} {r.path:<24} auth={r.auth} cache={r.cache} api_key={r.api_key} schema={'yes' if r.schema else 'no'} mapping={'yes' if r.mapping else 'no'}")
print("stages:", list(gw.stages), "· usage plans:", list(gw.plans))
EOF

✅ Verify — what you should see

kinds prints three lines: REST API the full kit: API keys + usage plans, caching, request validation, mapping templates, WAF, private, HTTP API lean and cheaper: JWT authorizers built in, CORS in one setting, Lambda + HTTP proxy, WebSocket API a phone line that stays open: $connect, $disconnect, routes by a field in the message, then this lab models a REST API because it shows the most parts.

Your snippet prints eight routes. Three of them use REST-only drawers: GET /students/{id} auth=None cache=True api_key=False schema=no mapping=yes (cache and mapping), POST /marks auth=jwt cache=False api_key=False schema=yes mapping=no (validation) and GET /partner/students/{id} auth=None cache=False api_key=True schema=no mapping=no (API key). Then stages: ['dev', 'prod'] · usage plans: ['partner-basic']. An HTTP API could not hold the cache, the validator, the mapping or the usage plan.

🏁 What you just proved

You can read an API's needs and name the kind: this school API uses a cache, a validator, a mapping and a usage plan, so it needs a REST API. Without those four, an HTTP API would do the same job for less.

⚠️ Common mistakes

choosing REST by habit for a plain "JWT + Lambda" API — HTTP is cheaper and simpler
choosing HTTP and later needing usage plans, caching or WAF — plan the feature list first
using WebSocket for a request that takes one answer — a normal request is simpler
polling every second for news when a WebSocket (or a push service) would call back

🏭 In production

On a real account — the same students route as an HTTP API (AWS SAM) and as a REST API (AWS SAM), side by side:

# template.yaml — AWS SAM
Resources:
  StudentsFn:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.12
      Handler: app.handler
      CodeUri: src/
      Events:
        LeanCounter:                       # HTTP API
          Type: HttpApi
          Properties: { Path: /students/{id}, Method: GET }
        FullOffice:                        # REST API
          Type: Api
          Properties: { Path: /students/{id}, Method: GET }

A WebSocket API picks its route from the message body:

aws apigatewayv2 create-api --name school-live --protocol-type WEBSOCKET \
    --route-selection-expression '$request.body.action'

🏭 Why this matters in production: the kind is hard to change later — clients, domains and authorizers are built around it. Write down the features you need (keys? cache? WAF? private?) before you create the API.

⏭️ Next

The office is chosen. Now: which desk takes which visitor? Routes and integrations.

git checkout lesson-03-routes-integrations

← Previouswhy gateway Next →routes integrations

This page is the lesson's README from the lesson-02-rest-http-websocket branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.