API ခြုံငုံသုံးသပ်ချက်

စနစ်အချင်းချင်း ချိတ်ဆက်ရန်အတွက် FreeMaint တွင် API မျက်နှာပြင် တစ်ခုသာ ရှိသည် — /api/v1/graphql ရှိ GraphQL ဖြစ်သည်။ ဘရောက်ဇာတွင် မြင်ရသော REST လမ်းကြောင်းများသည် အက်ပ်၏ ကိုယ်ပိုင် API ဖြစ်ပြီး အသုံးပြုသူ session ဖြင့် အတည်ပြုသည် — API key ဖြင့် မရောက်ရှိနိုင်ပါ။ ချိတ်ဆက်မှုကို GraphQL ပေါ်တွင် စီစဉ်ပါ။

REST API

/api/v1/{resource} အောက်ရှိ REST လမ်းကြောင်းများသည် FreeMaint ဝဘ်နှင့် မိုဘိုင်းအက်ပ်များ ခေါ်သုံးသည့် လမ်းကြောင်းများဖြစ်ပြီး အသုံးပြုသူ session (JWT) ဖြင့် အတည်ပြုသည်။ API key (fmk_...) ဖြင့် ၎င်းတို့ကို အတည်မပြုနိုင်ပါ — /api/v1/graphql နှင့် စွမ်းအင်ဒေတာ လက်ခံသည့် endpoint တွင်သာ လက်ခံသည်။ ချိတ်ဆက်ရန် အောက်ပါ GraphQL အပိုင်းကို ဖတ်ပါ။

ဥပမာ (အသုံးပြုသူ session ဖြစ်ပြီး API key မဟုတ်ပါ — fmk_ key ဖြင့် ဤလမ်းကြောင်းကို အတည်မပြုနိုင်ပါ)- curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL API

GraphQL လမ်းကြောင်းမှာ POST /api/v1/graphql ဖြစ်သည်။ ၎င်းသည် ထုတ်ကုန်၏ အစိတ်အပိုင်းတစ်ခုကိုသာ ရည်ရွယ်ချက်ရှိရှိ လွှမ်းခြုံသည် — လုပ်ငန်းအမိန့်များ၊ ပိုင်ဆိုင်မှုများ၊ စက်ရပ်နားမှုများ၊ အပိုပစ္စည်းများနှင့် ၎င်းတို့၏ စတော့ရွှေ့ပြောင်းမှုများ၊ မီတာများ၊ ဝယ်ယူမှုအမိန့်များ၊ တည်နေရာများ၊ ပေးသွင်းသူများ၊ ဖောက်သည်များနှင့် အဆောက်အအုံပုံစံများ — အက်ပ်လီကေးရှင်းတစ်ခုလုံး မဟုတ်ပါ။ ဖန်သားပြင်တစ်ခုတည်းကို တည်ဆောက်ရန် လမ်းကြောင်းများစွာ ခေါ်ရမည်ဆိုပါက GraphQL ကို သုံးပါ — ဥပမာ လုပ်ငန်းအမိန့်တစ်ခုကို ၎င်း၏ပိုင်ဆိုင်မှုအသေးစိတ်၊ သုံးစွဲခဲ့သော အပိုပစ္စည်းများနှင့် စုစုပေါင်းလုပ်အားခဖြင့် ပြသသည့် အကွက်တစ်ခု။ schema မရောက်ရှိသည်များကို ERP ပေါင်းစပ်မှုလမ်းညွှန်တွင် စာရင်းပြုထားသည်။

ဥပမာ query: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

အထောက်အထား စိစစ်ခြင်း

API နှစ်ခုစလုံးသည် Authorization ခေါင်းစီးရှိ JWT တိုကင်ကို လက်ခံသည်။ ၎င်းကို POST /api/v1/auth/login မှ ထုတ်ပေးပြီး 2 နာရီ သက်တမ်းရှိသည် (သက်တမ်းတိုးတိုကင်ဖြင့် သက်တမ်းတိုးနိုင်)။ ဆာဗာချင်းဆက်သွယ်မှုအတွက် API ကီးကို အသုံးပြုပါ — စီမံခန့်ခွဲသူက ကုမ္ပဏီဆက်တင်များ > API (/company-settings/api) တွင် ဖန်တီးပြီး၊ အခန်းကဏ္ဍက ခွင့်ပြုထားသူသည် ကိုယ်ရေးအချက်အလက် > လုံခြုံရေး > API ကီးများ (/profile/api-keys) တွင် ကိုယ်ပိုင်ကီးများကို ဖန်တီးနိုင်သည်။ Authorization: Bearer fmk_... ကို ပို့ပါ။ ကီးတစ်ခုသည် ၎င်း၏ပိုင်ရှင်အဖြစ် လုပ်ဆောင်သည် — ပိုင်ရှင်၏ ခွင့်ပြုချက်များ ရှိပြီး ပိုင်ရှင်မြင်ရသည်များကိုသာ မြင်ရသည်။ အရေးကြီးသည်မှာ — API ကီးသည် GraphQL အဆုံးမှတ် (POST /api/v1/graphql)၊ စွမ်းအင်ဒေတာထည့်သွင်းသည့် အဆုံးမှတ်နှင့် /public-api/{whoami,ping} တို့ကိုသာ အတည်ပြုနိုင်ပြီး၊ REST အရင်းအမြစ်လမ်းကြောင်းများကို အတည်မပြုနိုင်ပါ — ၎င်းတို့အတွက် အသုံးပြုသူ JWT လိုအပ်သည်။

Tier အလိုက် ရရှိနိုင်မှု

Rate Limit များ

ခွဲတမ်းသည် ကုမ္ပဏီအလိုက် နေ့စဉ်ကောင်တာဖြစ်ပြီး GraphQL နှင့် စွမ်းအင်ဒေတာထည့်သွင်းသည့် endpoint တို့ မျှဝေသုံးကာ UTC 00:00 တွင် ပြန်လည်စတင်သည်။ Business သည် တစ်ရက် 5,000 ကြိမ်၊ Enterprise သည် 100,000 ကြိမ် ခွင့်ပြုသည်။ တုံ့ပြန်မှုတိုင်းတွင် X-RateLimit-Limit၊ X-RateLimit-Remaining နှင့် X-RateLimit-Reset ပါဝင်သည်။ မိနစ်အလိုက်ကာလနှင့် Retry-After header မရှိပါ။ REST မျက်နှာပြင်များတွင် ငြင်းပယ်မှုမှာ HTTP 403 ဖြစ်သည်။ GraphQL တွင် HTTP status မှာ 200 အတိုင်းရှိနေပြီး — GraphQL သည် အမြဲ 200 ပြန်ပေးသည် — ငြင်းပယ်မှုကို errors[0].extensions.code = FORBIDDEN တွင် တွေ့ရသည်။ GraphQL တွင် HTTP 403 ကို မစောင့်ပါနှင့်၊ errors array ကို ဖတ်ပါ။

Error ဖော်မတ်

အမှားတိုင်းတွင် HTTP အခြေအနေ၊ စက်ဖတ်နိုင်သော ကုဒ်နှင့် ဖတ်ရလွယ်သော မက်ဆေ့ချ် ပါဝင်သည်။ 4xx သည် client အမှားများ (စိစစ်ခြင်း၊ ခွင့်ပြုချက်၊ မတွေ့ရှိခြင်း) ဖြစ်ပြီး 5xx သည် ဆာဗာအမှားများဖြစ်ကာ exponential backoff ဖြင့် ပြန်လည်ကြိုးစားသင့်သည်။ GraphQL တွင် ကုဒ်သည် extensions.code ၌ ရှိပြီး သင်တိုက်ဆိုင်စစ်နိုင်သော တန်ဖိုးများမှာ BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT နှင့် TOO_MANY_REQUESTS တို့ဖြစ်သည်။ စိစစ်မှု မအောင်မြင်ပါက မက်ဆေ့ချ်က မှားယွင်းသည့် အကွက်များကို အတိအကျ ဖော်ပြသည် — ဥပမာ "quantity must be a number conforming to the specified constraints" — ထို့ကြောင့် သင့်စနစ်က မည်သည့်အကွက်ကို မှားပို့ခဲ့သည်ကို ခန့်မှန်းစရာ မလိုပါ။ ဘာနှင့်မျှ မကိုက်ညီသော ရှာဖွေမှုသည် အမှားမဟုတ်ပါ — part(barcode:) သည် null ကို ပြန်ပေးသည်။

တရားဝင် SDK များနှင့် ကိရိယာများ

လက်ရှိတွင် တရားဝင် client SDK မရှိသေးပါ။ GraphQL endpoint တွင် introspection ဖွင့်ထားသဖြင့် မည်သည့် GraphQL client (Apollo၊ graphql-codegen၊ Insomnia၊ Postman) မဆို သင့် API သော့ဖြင့် POST /api/v1/graphql သို့ ချိတ်၍ schema ကို ရှာဖွေနိုင်သည်။ သတ်မှတ် URL တစ်ခုတွင် static OpenAPI စာရွက်စာတမ်း သို့မဟုတ် SDL ဖိုင်ကို ယခုအချိန်တွင် ထုတ်ဝေခြင်း မရှိပါ။

Core နှင့် Starter တွင် API key မရရှိနိုင်ပါ။