လေ့ကျင့်ခန်း: API မှတ်တမ်းဖတ်ခြင်း Lab

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

မကျွမ်းကျင်သေးသော API တစ်ခုနှင့် ချိတ်ဆက်ရာတွင် အမှန်တကယ် အခက်ခဲဆုံးအချက်မှာ request code ရေးရခြင်းမဟုတ်ဘဲ မှတ်တမ်း (documentation) ကို မြန်မြန်ဆန်ဆန် တိကျစွာ ဖတ်တတ်ခြင်းပင် ဖြစ်သည်။ Advanced အခန်းတွင် အစစ်အမှန် docs စာမျက်နှာတစ်ခုကို အပိုင်းလိုက် ဖတ်နည်းကို လေ့လာခဲ့ပြီးဖြစ်သည်။

ဤလေ့ကျင့်ခန်းတွင် ထိုနည်းလမ်းကို ချက်ချင်းလက်တွေ့ကျင့်ကြည့်ရန် ရိုးရှင်းသော sample တစ်ခု ပေးထားသည်။ အောက်ပါသည် စိတ်ကူးဖန်တီးထားသော "Bookshelf API" မှတ်တမ်း အပိုင်းအစတစ်ခု ဖြစ်ပြီး၊ စာအုပ်ပြန်လည်သုံးသပ်ချက် app တစ်ခုအတွက် အစစ်အမှန် provider တစ်ခုက ရေးသလိုပင် ရေးထားသည်။

Base URL — request တိုင်း တည်ဆောက်ရာအခြေခံ လိပ်စာ
Authentication method — ခေါ်ဆိုသူဘယ်သူဖြစ်ကြောင်း request က ဘယ်လိုသက်သေပြသနည်း
Endpoint path နှင့် HTTP method — အတိအကျ ဘာကိုခေါ်ရမည်၊ ဘယ်လိုခေါ်ရမည်
လိုအပ်သော/မလိုအပ်သော parameters — path၊ query နှင့် default တန်ဖိုးများ
လိုအပ်သော headers — request တိုင်းနှင့်တွဲရမည့်အရာများ
Request body ပုံစံ — သို့မဟုတ် မလိုအပ်ကြောင်း အတည်ပြုချက်
Response ပုံစံ — ပြန်လာမည့် field များ
Error code များနှင့် rate limit — ဘာအမှားဖြစ်နိုင်သနည်း၊ ဘယ်နှစ်ကြိမ်ခေါ်နိုင်သနည်း

ထပ်ခါထပ်ခါသုံးနိုင်သည့် အလေ့အထ

ဤအချက်ကို ဤသင်ခန်းစာအတွက် လေ့ကျင့်ခန်းတစ်ခုတည်းအဖြစ်သာ မမှတ်ယူဘဲ၊ integration code စတင်မရေးမီ API အသစ်တိုင်းအတွက် run ရမည့် checklist အဖြစ် သဘောထားပါ။

ဤကိုးခုကို စနစ်တကျ အစဉ်လိုက် ရှာဖွေတတ်ခြင်းသည် ချောမွေ့သော integration တစ်ခုနှင့် နာရီများစွာ ခန့်မှန်းရသည့် trial-and-error ကြားက ကွာခြားချက် ဖြစ်သည်။

text

ANATOMY OF AN API DOC
---------------------
BOOKSHELF API DOCUMENTATION - LABELED PARTS
---------------------------------------------
[BASE URL]   https://api.bookshelf-demo.dev/v1
[AUTH]       Bearer Token via Authorization header

[ENDPOINT]   GET /books/{bookId}/reviews
[METHOD]     GET
[PARAMS]     path:  bookId (required)
             query: page (default 1)
                    limit (default 20, max 100)
[HEADERS]    Authorization: Bearer <token>  (required)
             Accept: application/json       (optional)
[BODY]       none (this is a GET request)
[RESPONSE]   { data: [ {id, rating, comment} ],
               meta: { page, totalPages } }
[ERRORS]     401 invalid token, 404 not found, 429 rate limit
[RATE LIMIT] 100 requests per minute per token

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

အောက်တွင် အတွေ့အကြုံရှိသော developer တစ်ဦးက Bookshelf API အပိုင်းအစကို ဘယ်လိုချဉ်းကပ်မည်ကို ဖော်ပြထားသည်၊ ကိုယ်တိုင်လေ့ကျင့်ခန်းလုပ်ပြီးမှ အဖြေစစ်ရန်အတွက် ဖြစ်သည်။

Base URL နှင့် Auth

base URL သည် path တိုင်း ပေါင်းထည့်ရမည့် ပုံသေ prefix ဖြစ်သည်။ auth line က Bearer Token ဟု ဆိုသောကြောင့် request တိုင်းတွင် Authorization: Bearer <token> header လိုအပ်သည်။

Endpoint၊ Method နှင့် Parameters

GET /books/{bookId}/reviews ကို ရှာပါ။ curly braces က bookId ကို လိုအပ်သော path parameter အဖြစ် ပြသည်။ page နှင့် limit query parameters တို့သည် default တန်ဖိုးရှိသောကြောင့် optional ဖြစ်သည်။

Headers နှင့် Body

Authorization သည် required ဖြစ်ပြီး Accept သည် optional ဖြစ်သည်။ GET request တစ်ခုအတွက် သဘာဝကျစွာ request body မရှိပါ။

Response၊ Errors နှင့် Limits

response တွင် data array နှင့် pagination အတွက် meta object ပါဝင်သည်။ error code (401၊ 404၊ 429) နှင့် rate limit တို့က calling code ကိုင်တွယ်ရမည့်အရာများကို ပြောပြသည်။

အောက်ပါ code sample က ဤဖတ်ရှုမှု လုပ်ငန်းစဉ်ကို documentation ပုံစံဖြင့် ရေးထားသော object တစ်ခုမှ ရှင်းလင်းသော summary ထုတ်ပေးသည့် ပြန်သုံးနိုင်သော script ငယ်တစ်ခုအဖြစ် ပြောင်းလဲပြထားသည်။

API မှတ်တမ်းတိုင်းမှ ခွဲထုတ်ရမည့် ကိုးခု - base URL၊ auth၊ endpoint/method၊ params၊ headers၊ body၊ response ပုံစံ၊ errors၊ rate limit။
path ထဲက curly braces (ဥပမာ {bookId}) သည် အစစ်အမှန် တန်ဖိုးဖြင့် အစားထိုးရမည့် လိုအပ်သော path parameter ကို ဖော်ပြသည်။
default တန်ဖိုးပါသော parameter သည် optional ဖြစ်သည် — ထို default ကို ပြောင်းလိုမှသာ ပေးပို့ရန် လိုသည်။

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

javascript

const bookshelfApiDocs = {
  baseUrl: "https://api.bookshelf-demo.dev/v1",
  auth: {
    type: "Bearer Token",
    header: "Authorization: Bearer <token>"
  },
  endpoint: {
    method: "GET",
    path: "/books/{bookId}/reviews",
    description: "Returns a paginated list of reviews for one book.",
    pathParams: [
      { name: "bookId", type: "string", required: true, description: "The book's unique ID." }
    ],
    queryParams: [
      { name: "page", type: "integer", required: false, default: 1, description: "Page number." },
      { name: "limit", type: "integer", required: false, default: 20, description: "Max 100 per page." }
    ],
    headers: [
      { name: "Authorization", required: true, description: "Bearer <token>" },
      { name: "Accept", required: false, description: "application/json" }
    ],
    requestBody: null,
    responseShape: {
      data: [{ id: "string", rating: "number", comment: "string" }],
      meta: { page: "integer", totalPages: "integer" }
    },
    errors: [
      { status: 401, meaning: "Missing or invalid bearer token" },
      { status: 404, meaning: "Book not found" },
      { status: 429, meaning: "Rate limit exceeded" }
    ],
    rateLimit: "100 requests per minute per token"
  }
};

function summarizeEndpoint(doc) {
  const e = doc.endpoint;
  const lines = [];
  lines.push(`Base URL: ${doc.baseUrl}`);
  lines.push(`Auth: ${doc.auth.type} -> ${doc.auth.header}`);
  lines.push(`Call: ${e.method} ${doc.baseUrl}${e.path}`);

  const requiredPath = e.pathParams.filter(p => p.required).map(p => p.name);
  if (requiredPath.length) {
    lines.push(`Required path params: ${requiredPath.join(", ")}`);
  }

  const optionalQuery = e.queryParams
    .filter(p => !p.required)
    .map(p => `${p.name} (default ${p.default})`);
  if (optionalQuery.length) {
    lines.push(`Optional query params: ${optionalQuery.join(", ")}`);
  }

  const requiredHeaders = e.headers.filter(h => h.required).map(h => h.name);
  lines.push(`Required headers: ${requiredHeaders.join(", ")}`);
  lines.push(`Request body: ${e.requestBody ? "yes" : "none"}`);
  lines.push(`Possible error codes: ${e.errors.map(err => err.status).join(", ")}`);
  lines.push(`Rate limit: ${e.rateLimit}`);
  return lines.join("\n");
}

console.log(summarizeEndpoint(bookshelfApiDocs));

You should see

Base URL: https://api.bookshelf-demo.dev/v1
Auth: Bearer Token -> Authorization: Bearer <token>
Call: GET https://api.bookshelf-demo.dev/v1/books/{bookId}/reviews
Required path params: bookId
Optional query params: page (default 1), limit (default 20)
Required headers: Authorization
Request body: none
Possible error codes: 401, 404, 429
Rate limit: 100 requests per minute per token
(ဤ output သည် object ထဲမှ တန်ဖိုးများကို function က ဖတ်၍ ထုတ်ပေးထားခြင်း ဖြစ်သည်)

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

practical အပိုင်းရှိ walkthrough ကို မဖတ်မီ "Bookshelf API" sample မှတ်တမ်းကို ကိုယ်တိုင်ဖတ်ပြီး အောက်ပါတို့ကို ချရေးပါ - (၁) base URL၊ (၂) authentication method နှင့် ဘယ်လိုပေးပို့ရမည်၊ (၃) endpoint ၏ path နှင့် HTTP method၊ (၄) လိုအပ်သော/မလိုအပ်သော parameters နှင့် ၎င်းတို့၏ default များ၊ (၅) လိုအပ်သော headers များ၊ (၆) request body ရှိမရှိ၊ (၇) အောင်မြင်သော response ပုံစံ၊ (၈) မှတ်တမ်းတွင်ဖော်ပြထားသော error code တစ်ခုစီနှင့် ၎င်းတို့ ဘာကြောင့်ဖြစ်နိုင်သည်၊ (၉) ဖော်ပြထားသော rate limit။ ထို့နောက် အောက်ပါ walkthrough နှင့် အဖြေတစ်ခုချင်းစီကို နှိုင်းယှဉ်စစ်ဆေးပါ။

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

optional parameter ကို မလိုအပ်ဟု ယူဆပြီး ၎င်းရှိရခြင်း အကြောင်းရင်းကို မဖတ်ဘဲ ကျော်သွားခြင်း — optional param အချို့သည် အပြုအမူကို သိသိသာသာ ပြောင်းလဲနိုင်သည် (ဥပမာ limit က response size နှင့် rate-limit သုံးစွဲမှုကို သက်ရောက်စေခြင်း)။

error code နှင့် rate limit အပိုင်းများကို integration က production တွင် အမှန်တကယ် ပျက်စီးမှသာ အရေးကြီးကြောင်း သိလာသည်အထိ ကျော်ဖတ်ခြင်း။

Stripe API Reference (real-world example of a well-documented API) — API Integration & Webhooks