API Documentation Checklist

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

documentation ကို တစ်ကြိမ်ဖတ်ပြီး code ထဲ ချက်ချင်းဆင်းသွားတာက integration surprise အများစု ဖြစ်ပေါ်စေတဲ့ အကြောင်းရင်းပါ။ checklist တစ်ခုက "docs ဖတ်ပြီးပြီ" ဆိုတာကို စစ်ဆေးနိုင်တဲ့ တိကျသော list တစ်ခုအဖြစ် ပြောင်းပေးပါတယ်။

integration code မရေးခင် docs ကို ထပ်မဖွင့်ဘဲ base URL, auth method, လိုအပ်သော headers, ခေါ်ဆိုနေသော endpoint နှင့် method, query/path parameters လိုအပ်ကြောင်း ပြောနိုင်ရပါမယ်။

request body ပုံစံ (ရှိလျှင်), response schema, documented error codes, rate limits တို့ကိုလည်း သိရမည် — webhook support, SDK availability, API version, usage limits လို integration-level အချက်များနှင့်တကွ။

PRE-FLIGHT CHECK BEFORE INTEGRATING
-----------------------------------
READ THE DOCS
     |
     v
TICK THROUGH EACH CHECKLIST ITEM
   [x] base URL          [x] response schema
   [x] auth method        [x] error codes
   [x] required headers   [ ] rate limits
   [x] endpoint + method  [ ] webhooks?
   [x] query/path params  [ ] SDK available?
   [x] request body       [ ] API version
     |
     +-- any [ ] left? --> GAPS FOUND -> back to the docs
     |
     +-- all [x]?       --> READY TO INTEGRATE

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

payments provider တစ်ခုတည်းကို integrate လုပ်တော့မယ့် developer နှစ်ဦး ရှိတယ်ဆိုပါစို့။ ပထမတစ်ဦးမှာ checklist item ဆယ့်လေးခုထဲက ဆယ့်သုံးခု ဖြည့်ပြီးသား စာရွက်တစ်ခု ရှိပြီး API version တစ်ခုပဲ ကျန်နေတယ်။ ဒုတိယတစ်ဦးမှာ ဘာမှ ချမှတ်ထားခြင်း မရှိပါ။

အောက်က code က ဒီကွာခြားချက်ကို အတိအကျ model လုပ်ပါတယ် — "what I know" object ကို checklist နှင့် နှိုင်းယှဉ်စစ်ဆေးပြီး mostly-complete case နှင့် mostly-incomplete case နှစ်ခုအတွက် ဘာတွေကျန်နေသေးလဲ တိကျစွာ အစီရင်ခံပါတယ်။

• checklist တစ်ခုက "docs ဖတ်ပြီးပြီ" ဆိုတာကို ရှိတယ်/မရှိဘူး ပြောနိုင်တဲ့ list တစ်ခုအဖြစ် ပြောင်းပေးပါတယ် — အသင့်ဖြစ်တယ်ဆိုတဲ့ ခံစားချက် မဟုတ်ပါ။
• item ဆယ့်လေးခုက request mechanics (URL, auth, headers, endpoint, params, body, schema, errors) နှင့် integration-level အချက်များ (rate limits, webhooks, SDK, version) ကို ဖုံးလွှမ်းပါတယ်။
• ပျောက်နေသော item မှန်သမျှသည် docs ကို ပြန်သွားပြီး ပိတ်ရမည့် ကွက်လပ်တစ်ခုဖြစ်ပြီး production မှာမှ ခန့်မှန်းစမ်းသိရမည့်အရာ မဟုတ်ပါ။

API Documentation Checklist

• Base URL
• Authentication method
• လိုအပ်သော Headers
• Endpoint
• HTTP Method
• Query Parameters
• Path Parameters
• Request Body ပုံစံ
• Response Schema
• Error Codes
• Rate Limits
• Webhook ရရှိနိုင်မှု
• SDK ရရှိနိုင်မှု
• API Version

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

// The pre-flight checklist, as keys we can check for
// truthiness/presence.
const CHECKLIST_ITEMS = [
  "baseUrl",
  "authMethod",
  "requiredHeaders",
  "endpoint",
  "httpMethod",
  "queryParams",
  "pathParams",
  "requestBodyShape",
  "responseSchema",
  "errorCodes",
  "rateLimits",
  "webhooksAvailable",
  "sdkAvailable",
  "apiVersion",
];

// Returns which checklist items are still unknown/missing from what
// you've gathered so far about the API you're about to integrate.
function checkReadiness(knownInfo) {
  const missing = CHECKLIST_ITEMS.filter((item) => {
    const value = knownInfo[item];
    return value === undefined || value === null || value === "";
  });
  return {
    total: CHECKLIST_ITEMS.length,
    known: CHECKLIST_ITEMS.length - missing.length,
    missing,
    readyToIntegrate: missing.length === 0,
  };
}

const mostlyComplete = {
  baseUrl: "https://api.examplepay.dev/v1",
  authMethod: "Bearer token",
  requiredHeaders: ["Authorization", "Content-Type"],
  endpoint: "/payments",
  httpMethod: "POST",
  queryParams: [],
  pathParams: [],
  requestBodyShape: { amount: "number", currency: "string" },
  responseSchema: { id: "string", status: "string" },
  errorCodes: [400, 401, 500],
  rateLimits: "100 requests/minute",
  webhooksAvailable: true,
  sdkAvailable: false,
  // apiVersion left out on purpose
};

const mostlyIncomplete = {
  baseUrl: "https://api.examplepay.dev/v1",
  authMethod: "Bearer token",
};

console.log("Mostly complete:", checkReadiness(mostlyComplete));
console.log("Mostly incomplete:", checkReadiness(mostlyIncomplete));

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

Mostly complete: {
  total: 14,
  known: 13,
  missing: [ 'apiVersion' ],
  readyToIntegrate: false
}
Mostly incomplete: {
  total: 14,
  known: 2,
  missing: [
    'requiredHeaders',
    'endpoint',
    'httpMethod',
    'queryParams',
    'pathParams',
    'requestBodyShape',
    'responseSchema',
    'errorCodes',
    'rateLimits',
    'webhooksAvailable',
    'sdkAvailable',
    'apiVersion'
  ],
  readyToIntegrate: false
}

နှစ်ခုစလုံး readyToIntegrate: false ဖြစ်ပေမယ့် အကြောင်းရင်း လုံးဝကွာပါတယ် — item တစ်ခု ပျောက်ခြင်းနှင့် ဆယ့်နှစ်ခု ပျောက်ခြင်း — ရိုးရိုး "docs ဖတ်ပြီးပြီလား" ဆိုတဲ့ မေးခွန်းက ခွဲခြားပြနိုင်မည်မဟုတ်တဲ့ ကွာခြားချက်ပါပဲ။

Google API Design Guide — API Integration & Webhooks