API Documentation ဖတ်နည်း

နားလည်ထားရမယ့် အချက်

Provider တိုင်းက documentation ကို ကွဲပြားစွာ ရေးကြပါတယ်၊ ဒါပေမယ့် ခွဲထုတ်ရမည့်အချက်တွေက အမြဲတူတူပါပဲ။ ဒီအချက်တွေကို အစဉ်လိုက် ရှာတတ်ခြင်းက docs စာမျက်နှာကို ကုမ္ပဏီမည်သည့်ဆိုသည်နှင့် မဆိုင်ဘဲ checklist တိုတိုလေးတစ်ခုအဖြစ် ပြောင်းပေးပါတယ်။

အပေါ်ဆုံးက စတင်ပါ — request တိုင်း တည်ဆောက်ရာအခြေခံ base URL နှင့် API တစ်ခုလုံး လိုအပ်တဲ့ authentication method။ ဒါတွေက endpoint အားလုံးနီးပါးမှာ သက်ဆိုင်တဲ့အတွက် တစ်ကြိမ်ရှာလိုက်ရင် ထပ်တွက်စရာမလိုပါ။

Endpoint ၏ HTTP method နှင့် path, လိုအပ်သော path parameters (ဥပမာ {id}) အပါအဝင်။
Query parameters — ဘယ်တွေ required ဖြစ်ပြီး ဘယ်တွေမှာ default ရှိလဲ (optional ဟု ဆိုလိုသည်)။
Authentication အပြင် လိုအပ်သော headers, method က body ပို့ရင် body ပုံစံ။
အောင်မြင်သော response ပုံစံ, ဖော်ပြထားသော error code များနှင့် rate limit ရှိလျှင်။

ဒါက ကုမ္ပဏီတစ်ခုတည်းရဲ့ layout နဲ့ ဆိုင်တာ မဟုတ်ပါဘူး။ Stripe, GitHub, documentation နည်းနည်းသာရှိသော internal API — အချက်ကိုးချက်တူတူပဲ တစ်နေရာရာမှာ ရှိပါတယ်၊ skill ဆိုတာ ဘာကို ဘယ်အစီအစဉ်နဲ့ ရှာရမလဲ တိကျစွာ သိထားခြင်းပါပဲ။

text

PARTS OF A DOCUMENTATION PAGE, IN READING ORDER
-----------------------------------------------
BASE URL  ->  AUTH  ->  ENDPOINT  ->  METHOD
                                              |
                                              v
RESPONSE  <-  BODY  <-  HEADERS  <-  PARAMETERS
   |
   v
ERRORS

လက်တွေ့ scenario နဲ့ ချိတ်ကြည့်မယ်

ရှာသင့်တဲ့ အစိတ်အပိုင်းများနှင့် ကိုက်ညီတဲ့ စိတ်ကူးဖန်တီးထား "Payments API" အပိုင်းအစတစ်ခု — base URL, Bearer auth, endpoint တစ်ခု (Get Payment Status: GET /payments/{paymentId}) required path parameter နှင့် optional query parameter တစ်ခုနှင့်တကွ။

Base URL နှင့် Auth (နေရာတိုင်းသက်ဆိုင်)

https://api.examplepay.dev/v1 နှင့် Authorization header ထဲက Bearer token ကို ခေါ်ဆိုမှုတိုင်းအတွက် တစ်ကြိမ်တည်း သတ်မှတ်ပါ။

ဒီ Endpoint ၏ Path နှင့် Parameters

{paymentId} ထဲကို payment ID စစ်စစ် အစားထိုးပါ။ include query parameter သည် optional ဖြစ်၍ မလိုအပ်ပါက ကျော်ပါ။

Headers နှင့် Body

Authorization header တစ်ခုတည်းသာ လိုအပ်ပါသည်။ GET ဖြစ်သောကြောင့် request body မပို့ပါ။

Response နှင့် Errors

အောင်မြင်ရင် { id, status } မျှော်လင့်ပါ။ document လုပ်ထားသော failure နှစ်မျိုးတည်း — 401, 404 — ကိုသာ ကိုင်တွယ်ရန် code ပြင်ဆင်ပါ။

base URL နှင့် auth method ကို အရင်ရှာပါ — endpoint အားလုံးနီးပါးမှာ သက်ဆိုင်တဲ့အတွက် API တစ်ခုလျှင် တစ်ကြိမ်ပဲ ရှာပါ။
path ထဲက braces သို့မဟုတ် colon (ဥပမာ {id}) သည် လိုအပ်သော path parameter ကို ဖော်ပြသည်; documented default ရှိသော query parameter သည် optional ဖြစ်သည်။
ဤအချက်ကိုးချက် ဖတ်ရှုသည့်အစီအစဉ် — base URL, auth, endpoint, method, params, headers, body, response, errors — ကို provider မည်သူ့ docs အတွက်မဆို သုံးနိုင်ပါတယ်။

အတူတူ စမ်းရေးကြည့်မယ်

python

# A small fictional documentation excerpt, shaped like a real
# provider's docs (base URL, auth, and a list of endpoints) -- for
# teaching only, not a real API.
sample_docs = {
    "baseUrl": "https://api.examplepay.dev/v1",
    "authType": "Bearer token in Authorization header",
    "endpoints": [
        {
            "name": "Create Payment",
            "method": "POST",
            "path": "/payments",
            "pathParams": [],
            "queryParams": [],
            "headers": ["Authorization", "Content-Type"],
            "requestBody": {"amount": "number", "currency": "string", "customerId": "string"},
            "responseBody": {"id": "string", "status": "string", "amount": "number"},
            "errors": [400, 401, 402, 500],
        },
        {
            "name": "Get Payment Status",
            "method": "GET",
            "path": "/payments/{paymentId}",
            "pathParams": ["paymentId"],
            "queryParams": ["include"],
            "headers": ["Authorization"],
            "requestBody": None,
            "responseBody": {"id": "string", "status": "string"},
            "errors": [401, 404],
        },
    ],
}


def summarize_endpoint(docs, endpoint_name):
    """Pull together everything needed to call one documented endpoint."""
    endpoint = next(
        (e for e in docs["endpoints"] if e["name"] == endpoint_name), None
    )
    if endpoint is None:
        return {"error": f'No endpoint named "{endpoint_name}" in these docs'}

    return {
        "call": f"{endpoint['method']} {docs['baseUrl']}{endpoint['path']}",
        "auth": docs["authType"],
        "pathParams": endpoint["pathParams"],
        "queryParams": endpoint["queryParams"],
        "headers": endpoint["headers"],
        "requestBody": endpoint["requestBody"],
        "responseBody": endpoint["responseBody"],
        "possibleErrors": endpoint["errors"],
    }


for name in ["Get Payment Status", "Refund Payment"]:
    print(f"--- {name} ---")
    summary = summarize_endpoint(sample_docs, name)
    for key, value in summary.items():
        print(f"{key}: {value}")
    print()

You should see

Run လုပ်ရင် ရလာမည့် တကယ့် output:

--- Get Payment Status ---
call: GET https://api.examplepay.dev/v1/payments/{paymentId}
auth: Bearer token in Authorization header
pathParams: ['paymentId']
queryParams: ['include']
headers: ['Authorization']
requestBody: None
responseBody: {'id': 'string', 'status': 'string'}
possibleErrors: [401, 404]

--- Refund Payment ---
error: No endpoint named "Refund Payment" in these docs

ဒုတိယခေါ်ဆိုမှုက document မလုပ်ခဲ့တဲ့ endpoint တစ်ခုကို တောင်းဆိုတာဖြစ်ပြီး function က ခန့်မှန်းမည့်အစား ရိုးသားစွာ အစီရင်ခံပါတယ် — တကယ့် docs က case တစ်ခုကို မဖုံးလွှမ်းတဲ့အခါ သင်လုပ်သင့်တဲ့ အလုပ်တူတူပါပဲ။

၅ မိနစ် စမ်းကြည့်

သင် တစ်ခါမှ မသုံးဖူးသေးသော public documented API endpoint တစ်ခုကို ရွေးပါ။ ဒီသင်ခန်းစာက ဖတ်ရှုအစီအစဉ်ကို သုံးပြီး ၎င်း၏ base URL, auth method, path (path parameters နှင့်တကွ), လိုအပ်သော headers, request body ပုံစံ (ရှိလျှင်), response ပုံစံ, error code များကို ငါးမိနစ်အတွင်း ချရေးပါ။

သတိလေးတစ်ချက်

documentation စာမျက်နှာကို checklist အတိအကျ မပါဘဲ အစအဆုံး ဖတ်ပြီး စာမျက်နှာအလယ်ပိုင်းမှာ ဝှက်နေတဲ့ လိုအပ်သော header ဒါမှမဟုတ် path parameter ကို လွတ်သွားခြင်း။

provider အားလုံးက term တူတူသုံးတယ်လို့ ယူဆခြင်း — တချို့က query parameters ကို "filters" လို့၊ တချို့က Bearer token ကို "access token" လို့ ခေါ်ကြပါတယ် — စာလုံးအတိအကျမက အဓိပ္ပာယ်ကို ဖတ်ပါ။

OpenAPI Specification — About — API Integration & Webhooks