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

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

🔌 धडा 03 — API design: आधी करार

📍 तुम्ही इथे आहात: 18 पैकी धडा 03 · मागे: lesson-02-capacity · पुढे: lesson-04-data-model

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

धडे 01–02, आणि पद्धतीची तिसरी पायरी: app आणि server यांच्यातला करार (contract), code च्या आधी लिहिलेला. कृतींऐवजी resources, योग्य status codes, पुन्हा पाठवलेली post दोनदा लागू नये म्हणून idempotency keys, OFFSET ऐवजी cursor pagination, आणि प्रकाशित field कधीही न मोडणारे versioning. design/demo.py मधील api() सूचना फलकाचा करार छापते; design/designs.py मधील pagination_cost() प्रत्येक प्रकारचे pagination database ला किती rows चालायला लावते ते मोजते.

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

नियोजन कार्यालय स्वतः हॉल बांधणार नाही. बांधकाम करणारे बांधतील — आणि सुतार, वीजतंत्री आणि रंगारी सगळे एकाच वेळी काम करतात. प्रत्येकाने दारे कुठे आहेत याचा अंदाज बांधला, तर काहीच जुळणार नाही.

म्हणून दीपिका आधी दारांचा आराखडा 🚪 काढते: हे दार मुलांना आत येण्यासाठी, ती खिडकी फॉर्म वाटण्यासाठी, आणि प्रत्येक दारावर तिथे काय होते ते सांगणारी पाटी. दारांच्या आराखड्यावर सही झाली की सगळे एकाच वेळी काम करू शकतात. App team आराखड्याप्रमाणे phone app बांधते; server team आराखड्याप्रमाणे server बांधते.

दीपिकाच्या आराखड्यात आणखी दोन नियम:

प्रत्येक फॉर्मवर एक शिक्का 🔖. पहिली सूचना पोहोचली की नाही याची खात्री नसल्याने एखाद्या शिक्षिकेने तीच सूचना दोनदा दिली, तर कार्यालय तोच शिक्का पाहते आणि ती दोनदा लावत नाही.
"इथून पुढे चालू ठेवा" चिठ्ठ्या 🔖. जुन्या सूचना वाचणाऱ्या पालकाला एका वेळी 20 सूचना आणि "सूचना 90 नंतर पुढे चालू ठेवा" अशी चिठ्ठी मिळते. कारकून थेट सूचना 90 कडे जाते — ती प्रत्येक वेळी पहिल्या सूचनेपासून पुन्हा मोजत नाही.

🗺️ आकृती

flowchart LR
    app["📱 parent / teacher app"]
    subgraph api["🔌 the contract · /v1"]
      p["POST /classes/3A/notices<br/>Idempotency-Key<br/>→ 201 + Location"]
      g["GET /classes/3A/notices<br/>?limit=20&cursor=…<br/>→ 200 {items, next_cursor}"]
      f["GET /parents/me/feed<br/>?limit=20"]
    end
    err["⚠️ 400 · 401 · 403 · 404 · 409 · 429"]
    pg["📄 page 5,000<br/>OFFSET walks 100,000 rows<br/>cursor walks 20"]
    app --> p
    app --> g
    app --> f
    api --> err
    g --> pg

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

❓ काय

API करार (contract) — requests, त्यांचे inputs, त्यांची उत्तरे आणि त्यांचे errors यांची लिहून ठेवलेली यादी (HTTP साठी, सहसा एका OpenAPI file मध्ये). Teams एकाच वेळी त्याच्या आधारे बांधतात.
कृती नव्हे, resources (REST) — URLs गोष्टींची नावे सांगतात (/classes/3A/notices), आणि HTTP method काय करायचे ते सांगते: GET वाचतो, POST बनवतो, PUT/PATCH बदलतो, DELETE काढून टाकतो. /postNotice किंवा /getNoticesForClass नाही.
Status codes — client सगळ्यात आधी वाचतो ती गोष्ट:
- 200 OK · 201 Created (+ नव्या सूचनेचा URL असलेला Location header)
- 400 चुकीचे input · 401 तुम्ही कोण? (login केलेले नाही) · 403 तुम्ही ओळखीचे आहात, पण हा तुमचा वर्ग नाही · 404 अशी गोष्ट नाही · 409 संघर्ष (conflict) · 429 हळू (धडा 12)
- 5xx — server अपयशी झाला; client नंतर retry करू शकतो.
Idempotency key — client POST वर एका header (Idempotency-Key) मध्ये ठेवतो तो एक अद्वितीय id. Server key आणि उत्तर लक्षात ठेवतो. तीच key पुन्हा आली (timeout नंतरचा retry), तर server पहिलेच उत्तर परत देतो आणि दुसरी सूचना बनवत नाही. GET, PUT आणि DELETE रचनेनेच idempotent आहेत; POST नाही — म्हणूनच त्याला key लागते. (तीच key वेगळ्या body सह वापरली, तर तो client चा bug: 409 किंवा 422 उत्तर द्या.)
Pagination — "सगळ्या सूचना" कधीच परत देऊ नका. एक page परत द्या:
- OFFSET (?page=5000 → OFFSET 99980 LIMIT 20) — सोपे, पण database आधीची प्रत्येक row चालतो आणि फेकून देतो. Page 5,000 100,000 rows चालतो. तुम्ही वाचत असताना जोडलेल्या rows pages सरकवतात, म्हणून एखादी सूचना दोनदा दिसते किंवा चुकते.
- Cursor (keyset) — उत्तरात next_cursor असतो, "मी पाठवलेल्या शेवटच्या item नंतर" याचे एक अपारदर्शक (opaque) token (eyJpZCI6OTB9 हे {"id":90} चे base64 आहे). Database index वापरून थेट तिथे seek करतो. प्रत्येक page फक्त 20 rows चालतो.
Versioning — version path मध्ये (/v1/…) किंवा header मध्ये ठेवा. प्रकाशित field कधीही मोडू नका: नवे fields जोडा, जुने rename किंवा काढू नका. जुने apps वर्षानुवर्षे phones वर राहतात.
REST vs gRPC vs GraphQL (थोडक्यात):
- REST + JSON — public आणि mobile APIs साठी default; cache ला सोयीचे, debug करायला सोपे.
- gRPC — binary, typed, जलद, streaming; तुमच्याच services मधल्या संवादासाठी चांगले.
- GraphQL — client ला हवे तेवढेच fields मागतो; वेगवेगळ्या गरजांच्या अनेक screens साठी चांगले, पण caching आणि rate limits अवघड होतात.

🤔 का

कारण API हा नंतर बदलायला सर्वात अवघड भाग आहे. त्यामागचा database तुम्ही एका weekend मध्ये बदलू शकता. 5 million phones ना app update करायला लावू शकत नाही. आणि करार रचनेची वचने वाहतो: network बिघडले तरी idempotency key "सूचना कधीही दोनदा post होत नाही" हे खरे ठेवते; cursor pagination page 5,000 वरही "read p99 < 200 ms" खरे ठेवते; 403 "पालकाला फक्त तिच्या मुलांचे वर्ग दिसतात" हे करारातच दिसणारे ठेवते (धडा 14).

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

design/demo.py मधील api() तीन calls आणि errors छापते, मग design/designs.py मधील pagination_cost(page, page_size, mode) ला विचारते की प्रत्येक mode किती rows चालतो: OFFSET साठी page × page_size, cursor साठी page_size. Snippet मध्ये तुम्ही एक छोटे idempotency store सुद्धा चालवता — key पासून उत्तरापर्यंतची एक dictionary — आणि timeout नंतर phone करतो तशी तीच key दोनदा पाठवता.

🧪 करून पाहा

python3 design/demo.py api
python3 - <<'EOF'
import sys; sys.path.insert(0, "design"); from designs import pagination_cost
for size in (20, 100):
    for page in (1, 500, 50_000):
        print(f"{size:>3} per page, page {page:>6,}: OFFSET {pagination_cost(page, size, 'offset'):>9,} rows · cursor {pagination_cost(page, size, 'cursor'):>3}")
seen = {}
def post(key, body):
    if key in seen: return 200, seen[key], "replayed"
    seen[key] = f"notice-{len(seen) + 1}"; return 201, seen[key], "created"
print(post("k-7f3a", {"title": "Trip"}))
print(post("k-7f3a", {"title": "Trip"}))   # the phone retried after a timeout
print(post("k-9b21", {"title": "Exam"}))
EOF

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

api छापते:

── the contract first — resources, not actions:
   POST /classes/3A/notices          body {title, text, urgent} · header Idempotency-Key → 201 + Location
   GET  /classes/3A/notices?limit=20&cursor=eyJpZCI6OTB9 → 200 {items, next_cursor}
   GET  /parents/me/feed?limit=20   → the notices of all my children's classes
   errors: 400 bad input · 401 who are you · 403 not your class · 404 · 409 key reused with a different body · 429 slow down
── pagination: rows the database walks to show page N (20 per page)
   page     1: OFFSET walks      20 rows · a cursor walks  20
   page    50: OFFSET walks   1,000 rows · a cursor walks  20
   page  5000: OFFSET walks 100,000 rows · a cursor walks  20
   version in the path (/v1) or a header; never break a published field — add new ones

तुमचा snippet छापतो:

 20 per page, page      1: OFFSET        20 rows · cursor  20
 20 per page, page    500: OFFSET    10,000 rows · cursor  20
 20 per page, page 50,000: OFFSET 1,000,000 rows · cursor  20
100 per page, page      1: OFFSET       100 rows · cursor 100
100 per page, page    500: OFFSET    50,000 rows · cursor 100
100 per page, page 50,000: OFFSET 5,000,000 rows · cursor 100
(201, 'notice-1', 'created')
(200, 'notice-1', 'replayed')
(201, 'notice-2', 'created')

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

OFFSET चा खर्च page क्रमांकासोबत वाढतो — page 50,000 20 सूचना दाखवण्यासाठी दहा लाख rows चालतो. Cursor चा खर्च page 1 आणि page 50,000 वर सारखाच. आणि तीच Idempotency-Key दोनदा पाठवली की तीच सूचना परत मिळते (notice-1, दुसऱ्या वेळी 200 उत्तर) — एक सूचना, दोन नाही. नवी key नवी सूचना बनवते.

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

URLs मध्ये क्रियापदे: /createNotice, /getAllNotices
सगळ्यासाठी 200, आत {"error": …} — clients आणि load balancers ना फरक कळत नाही
401 आणि 403 ची गल्लत: 401 = "तुम्ही कोण?", 403 = "मी तुम्हाला ओळखतो; परवानगी नाही"
mobile network वर idempotency key शिवाय POST — प्रत्येक timeout duplicate चा धोका आणतो
limit शिवाय प्रत्येक row परत देणे; कायम वाढत जाणाऱ्या table वर OFFSET
प्रकाशित field "नवे नाव जास्त छान आहे म्हणून" rename करणे — जुने apps मोडतात
client वाचू आणि बदलू शकेल असा cursor (?after_id=90) आणि मग access साठी त्यावर विश्वास — तो opaque ठेवा, permissions प्रत्येक वेळी तपासा

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

करार repo मध्ये एका OpenAPI file म्हणून राहतो; server stubs, client code, docs आणि tests त्यापासून बनतात. सूचना फलकाच्या file चा एक भाग:

openapi: 3.1.0
info: { title: Notice board, version: "1.0" }
paths:
  /v1/classes/{classId}/notices:
    post:
      parameters:
        - { name: classId, in: path, required: true, schema: { type: string } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 64 } }
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NewNotice" }
      responses:
        "201": { description: Created, headers: { Location: { schema: { type: string } } } }
        "403": { description: Not your class }
        "409": { description: Key reused with a different body }
    get:
      parameters:
        - { name: limit, in: query, schema: { type: integer, maximum: 100, default: 20 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        "200": { description: A page of notices, newest first }

Server चालवतो ती cursor query — index वरचा keyset seek, प्रत्येक page वर तोच खर्च:

SELECT id, title, created_at FROM notices
WHERE class_id = '3A' AND (created_at, id) < ($1, $2)   -- values decoded from the cursor
ORDER BY created_at DESC, id DESC LIMIT 20;

On a real account — service च्या पुढे असलेला API तुमचा code चालण्याआधीच करार तपासू शकतो, उदाहरणार्थ तीच OpenAPI file Amazon API Gateway मध्ये import करून:

aws apigateway import-rest-api --body fileb://openapi.yaml

अधिक खोलात: API शाळा (REST, status codes, auth, pagination, gRPC आणि GraphQL) आणि API Gateway शाळा.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: OpenAPI file code सारखीच review करा, आणि एखादा बदल प्रकाशित field काढतो किंवा rename करतो तेव्हा अपयशी होणारी तपासणी CI मध्ये चालवा. मोडणारे बदल हा निर्णय असायला हवा, अपघात कधीच नाही.

⏭️ पुढे

करार सांगतो app काय विचारतो. आता: उत्तर कुठे राहते? नियोजन कार्यालय data चे model त्याला विचारल्या जाणाऱ्या प्रश्नांवरून बनवते.

git checkout lesson-04-data-model

🔌 Lesson 03 — API design: the contract first

📍 You are here: Lesson 03 of 18 · Previous: lesson-02-capacity · Next: lesson-04-data-model

📦 What's in this branch

Lessons 01–02, plus the third step of the method: the contract between the app and the server, written before the code. Resources instead of actions, the right status codes, idempotency keys so a retried post is not posted twice, cursor pagination instead of OFFSET, and versioning that never breaks a published field. api() in design/demo.py prints the notice board's contract; pagination_cost() in design/designs.py counts the rows each kind of pagination makes the database walk.

🧒 Explain like I'm 5

The planning office will not build the hall itself. Builders will — and the carpenters, the electricians and the painters all work at the same time. If each one guesses where the doors are, nothing fits.

So Dipika draws the door plan first 🚪: this door is for children coming in, that window is for handing out forms, and every door has a sign that says what happens there. Once the door plan is signed, everyone can work in parallel. The app team builds the phone app to the plan; the server team builds the server to the plan.

Two more rules on Dipika's plan:

A stamp on every form 🔖. If a teacher hands in the same notice twice because she was not sure the first one arrived, the office sees the same stamp and does not pin it twice.
"Continue from here" slips 🔖. A parent reading old notices gets 20 at a time and a slip that says "continue after notice 90". The clerk goes straight to notice 90 — she does not count again from the first notice every time.

🗺️ Diagram

flowchart LR
    app["📱 parent / teacher app"]
    subgraph api["🔌 the contract · /v1"]
      p["POST /classes/3A/notices<br/>Idempotency-Key<br/>→ 201 + Location"]
      g["GET /classes/3A/notices<br/>?limit=20&cursor=…<br/>→ 200 {items, next_cursor}"]
      f["GET /parents/me/feed<br/>?limit=20"]
    end
    err["⚠️ 400 · 401 · 403 · 404 · 409 · 429"]
    pg["📄 page 5,000<br/>OFFSET walks 100,000 rows<br/>cursor walks 20"]
    app --> p
    app --> g
    app --> f
    api --> err
    g --> pg

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

❓ What

API contract — the list of requests, their inputs, their answers and their errors, written down (for HTTP, usually as an OpenAPI file). Teams build against it in parallel.
Resources, not actions (REST) — URLs name things (/classes/3A/notices), and the HTTP method says what to do: GET reads, POST creates, PUT/PATCH changes, DELETE removes. Not /postNotice or /getNoticesForClass.
Status codes — the first thing a client reads:
- 200 OK · 201 Created (+ a Location header with the new notice's URL)
- 400 bad input · 401 who are you? (not logged in) · 403 you are known, but this is not your class · 404 no such thing · 409 conflict · 429 slow down (lesson 12)
- 5xx — the server failed; the client may retry later.
Idempotency key — a unique id the client puts in a header (Idempotency-Key) on a POST. The server remembers the key and the answer. If the same key arrives again (a retry after a timeout), the server returns the first answer and does not create a second notice. GET, PUT and DELETE are idempotent by design; POST is not — that is why it needs the key. (A key reused with a different body is a client bug: answer 409 or 422.)
Pagination — never return "all notices". Return a page:
- OFFSET (?page=5000 → OFFSET 99980 LIMIT 20) — simple, but the database walks and throws away every earlier row. Page 5,000 walks 100,000 rows. Rows added while you read also shift the pages, so you see a notice twice or miss one.
- Cursor (keyset) — the answer carries next_cursor, an opaque token for "after the last item I sent you" (eyJpZCI6OTB9 is base64 for {"id":90}). The database seeks straight there with an index. Every page walks 20 rows.
Versioning — put the version in the path (/v1/…) or a header. Never break a published field: add new fields, do not rename or remove old ones. Old apps stay on phones for years.
REST vs gRPC vs GraphQL (briefly):
- REST + JSON — the default for public and mobile APIs; cache-friendly, easy to debug.
- gRPC — binary, typed, fast, streaming; good between your own services.
- GraphQL — the client asks for exactly the fields it needs; good for many screens with different needs, but caching and rate limits are harder.

🤔 Why

Because the API is the part that is hardest to change later. You can swap a database behind it in a weekend. You cannot make 5 million phones update their app. And the contract carries the design's promises: the idempotency key keeps "a notice is never posted twice" true when networks fail; cursor pagination keeps "read p99 < 200 ms" true on page 5,000; 403 keeps "a parent sees only her children's classes" visible in the contract (lesson 14).

🔧 How (in this repo)

api() in design/demo.py prints the three calls and the errors, then asks pagination_cost(page, page_size, mode) in design/designs.py how many rows each mode walks: page × page_size for OFFSET, page_size for a cursor. In the snippet you also run a tiny idempotency store — a dictionary from key to answer — and send the same key twice, the way a phone does after a timeout.

🧪 Try it

python3 design/demo.py api
python3 - <<'EOF'
import sys; sys.path.insert(0, "design"); from designs import pagination_cost
for size in (20, 100):
    for page in (1, 500, 50_000):
        print(f"{size:>3} per page, page {page:>6,}: OFFSET {pagination_cost(page, size, 'offset'):>9,} rows · cursor {pagination_cost(page, size, 'cursor'):>3}")
seen = {}
def post(key, body):
    if key in seen: return 200, seen[key], "replayed"
    seen[key] = f"notice-{len(seen) + 1}"; return 201, seen[key], "created"
print(post("k-7f3a", {"title": "Trip"}))
print(post("k-7f3a", {"title": "Trip"}))   # the phone retried after a timeout
print(post("k-9b21", {"title": "Exam"}))
EOF

✅ Verify — what you should see

api prints:

── the contract first — resources, not actions:
   POST /classes/3A/notices          body {title, text, urgent} · header Idempotency-Key → 201 + Location
   GET  /classes/3A/notices?limit=20&cursor=eyJpZCI6OTB9 → 200 {items, next_cursor}
   GET  /parents/me/feed?limit=20   → the notices of all my children's classes
   errors: 400 bad input · 401 who are you · 403 not your class · 404 · 409 key reused with a different body · 429 slow down
── pagination: rows the database walks to show page N (20 per page)
   page     1: OFFSET walks      20 rows · a cursor walks  20
   page    50: OFFSET walks   1,000 rows · a cursor walks  20
   page  5000: OFFSET walks 100,000 rows · a cursor walks  20
   version in the path (/v1) or a header; never break a published field — add new ones

Your snippet prints:

 20 per page, page      1: OFFSET        20 rows · cursor  20
 20 per page, page    500: OFFSET    10,000 rows · cursor  20
 20 per page, page 50,000: OFFSET 1,000,000 rows · cursor  20
100 per page, page      1: OFFSET       100 rows · cursor 100
100 per page, page    500: OFFSET    50,000 rows · cursor 100
100 per page, page 50,000: OFFSET 5,000,000 rows · cursor 100
(201, 'notice-1', 'created')
(200, 'notice-1', 'replayed')
(201, 'notice-2', 'created')

🏁 What you just proved

OFFSET cost grows with the page number — page 50,000 walks a million rows to show 20. A cursor costs the same on page 1 and page 50,000. And the same Idempotency-Key sent twice gives back the same notice (notice-1, answered 200 the second time) — one notice, not two. A new key makes a new notice.

⚠️ Common mistakes

verbs in URLs: /createNotice, /getAllNotices
200 for everything, with {"error": …} inside — clients and load balancers cannot tell
401 and 403 mixed up: 401 = "who are you?", 403 = "I know you; not allowed"
POST with no idempotency key on a mobile network — every timeout risks a duplicate
returning every row with no limit; OFFSET on a table that grows forever
renaming a published field "because the new name is nicer" — old apps break
a cursor the client can read and change (?after_id=90) and then trusts for access — keep it opaque, check permissions every time

🏭 In production

The contract lives in the repo as an OpenAPI file; server stubs, client code, docs and tests are made from it. Part of the notice board's file:

openapi: 3.1.0
info: { title: Notice board, version: "1.0" }
paths:
  /v1/classes/{classId}/notices:
    post:
      parameters:
        - { name: classId, in: path, required: true, schema: { type: string } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 64 } }
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NewNotice" }
      responses:
        "201": { description: Created, headers: { Location: { schema: { type: string } } } }
        "403": { description: Not your class }
        "409": { description: Key reused with a different body }
    get:
      parameters:
        - { name: limit, in: query, schema: { type: integer, maximum: 100, default: 20 } }
        - { name: cursor, in: query, schema: { type: string } }
      responses:
        "200": { description: A page of notices, newest first }

The cursor query the server runs — a keyset seek on an index, the same cost on every page:

SELECT id, title, created_at FROM notices
WHERE class_id = '3A' AND (created_at, id) < ($1, $2)   -- values decoded from the cursor
ORDER BY created_at DESC, id DESC LIMIT 20;

On a real account — an API in front of the service can check the contract before your code runs, for example by importing the same OpenAPI file into Amazon API Gateway:

aws apigateway import-rest-api --body fileb://openapi.yaml

Go deeper: the API school (REST, status codes, auth, pagination, gRPC and GraphQL) and the API Gateway school.

🏭 Why this matters in production: review the OpenAPI file like code, and run a check in CI that fails when a change removes or renames a published field. Breaking changes should be a decision, never an accident.

⏭️ Next

The contract says what the app asks. Now: where does the answer live? The planning office models the data from the questions it will be asked.

git checkout lesson-04-data-model

← Previouscapacity Next →data model

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