API Specification Recommendation

blogs

“Function တစ်ခု ၁၀ မိနစ်လုပ်လိုက်ရတယ်၊ variable နာမည်တစ်လုံး ၁ နာရီကြာအောင်စဉ်းစားလိုက်ရတယ်” ဆိုတဲ့ programming ဟာသတစ်ခုကြားဖူးကြမှာပါ။ အဲ့လိုပဲ ကျွန်တော်တို့တွေ api တွေလုပ်တဲ့အချိန်မှာ ကြုံတွေ့ရတဲ့ သို့လောသို့လောဖြစ်စရာတစ်ခုကတော့ resource URL တွေကို ဘယ်လိုနာမည်ပေးမလဲဆိုတာပါပဲ။ api တင်မကပါဘူး web app တွေမှာလည်း ထိုနည်းတူပါပဲ။ စာအုပ်ငှားတဲ့ app တစ်ခုကိုစဉ်းစားကြည့်ကြတာပေါ့ဗျာ။ member စာရင်းပေးတဲ့ page ကို မောင်ဖြူကbookstore.com/members/reigster လို့ရေးပြီး မောင်နီက bookstore.com/register_member လို့ရေး၊ မစိမ်းပင်က bookstore.com/memberRegistration လို့ရေးတယ်ဆိုပြီးလုပ်ချလိုက်ရင် project ကို ဦးဆောင်ရတဲ့လူ တော်တော်ခေါင်းကိုက်မယ်ထင်ပါတယ်။ ကျွန်တော့်အတွက် resource URL တွေဟာ web developer တွေအတွက် first impression လို့ပဲထင်ပါတယ်။ ဒီ URL တွေကို စနစ်တကျ လှလှပပစီမံတတ်ခြင်းဟာ ဒီ developer ရဲ့ app တွေအပေါ်ထားတဲ့ ခံယူချက်ကိုထင်ဟတ်နေစေပါတယ်။ ဒါကြောင့်မို့လို့ smart ကျကျဝတ်စားဆင်ယဉ်တဲ့ developer တွေအတွက် smart ကျကျစီမံထားတဲ့ resource URL သတ်မှတ်စီစဉ်ပုံအကြံပြုချက်များကို ကျွန်တော်လေ့လာမိသလောက်ဖော်ပြပေးလိုက်ပါတယ်။

Route သတ်မှတ်သည့်နေရာတွင် အကြံပြုချက်များ

  •  API တွေကို “api” ဆိုပြီးစာသားကြားခံသုံးပါ။ ဒါဟာ ကျွန်တော်တို့ web app နဲ့ web api ကိုခွဲခြားပေးဖို့ကူညီပေးပါတယ်။  bookstore.com/members ကို POST request ဆိုရင် new 
              member create လုပ်မယ့် web app URL ဖြစ်ပြီးတော့ bookstore.com/api/members ကို POST request ဆိုရင် new member create လုပ်မဲ့ URL ဆိုပြီး လွယ်လွယ်ပဲသိရှိနိုင်ပါတယ်။
  • API version ကိုသုံးပါ။ bookstore.com/api/users လို့သုံးမဲ့အစား bookstore.com/api/v1/users ဆိုပြီးသုံးပါမယ်။ ဒီလိုလုပ်ခြင်းအားဖြင့် company ကနောက်ခါ api အသစ်လုပ်ချင်ပါ
            တယ်ဆိုရင်တောင် project အသစ်လုပ်စရာမလိုအောင် ကူညီပေးပါတယ်။
  • Route တွေမှာ အများကိန်းကိုသုံးပါ။ multi word ဆိုရင်တော့ အများကိန်းကိုမသုံးလည်းရပါတယ်။
           bookstore.com/api/v1/user/100 ဆိုပြီးရေးမဲ့အစား bookstore.com/api/v1/users/100 ဆိုပြီး အများကိန်းကိုသုံးတာက ပိုပြီးဖတ်ရတယ်လွယ်တယ်လို့ အကြံပြုထားပါတယ်။    
           /api/v1/users ဆိုရင် “API version 1 ထဲကနေ user list ကိုထုတ်ပေးပါ” ဆိုပြီး အဓိပ္ပာယ်ရပြီး /api/v1/users/100 ဆိုရင် “API version 1 ထဲကနေ user တွေထဲကမှ id 100 ရှိတဲ့ user ကို
           ထုတ်ပေးပါ”ဆိုပြီး အဓိပ္ပာယ်ရပါတယ်။
  • Route တွေမှာ verb (ကြိယာ) ကိုလိုအပ်မှ သုံးပါ။ စာလုံးတစ်လုံးထပ်ပိုသုံးချင်ရင် underscore (_) အစား hyphen(-) ကိုသုံးပါမယ်။
           api/v1/users ကို DELETE request ဆိုရင် user တစ်ယောက်ကို ဖျက်တာလို့သိနိုင်ပါတယ်။ မဖျက်ချင်ဘဲ deactivate ပဲလုပ်ချင်တာမျိုးဆိုရင်တော့ /api/v1/users/deactivate ဆိုပြီး သုံးနိုင်ပါ
           တယ်။ ဒီမှာဆို deactivate ဆိုပြီး ကြိယာကို သုံးထားပါတယ်။
           /api/v1/getUserList ဆိုပြီးသုံးတာမျိုးကို ရှောင်ပါလို့ဆိုလိုပါတယ်။ /api/v1/user-list/ ဆိုပြီးသုံးတာက ဖတ်ရတာပိုလွယ်ပါတယ်။
  • Route တွေမှာ nested pattern ကိုသုံးပါ။ ဥပမာ – user တစ်ယောက်ရဲ့ Book list ကိုထုတ်ပေးတဲ့ route ဆို /api/v1/users/{user_id}/books ဆိုပြီး လုပ်တာမျိုးကိုဆိုလိုပါတယ်။
  • HTTP status code တွေကိုသုံးပါ။ operation အောင်မြင်တဲ့ response code တွေကို 2** တွေကို သုံးရပါမယ်။ error တွေဆိုရင်တော့ user error ဆို 4**, program error ဆို 5** ကိုအလျ
           သင့်သလို သုံးပါမယ်။
           GET – 200 (success)
           POST – 201 (success)
           PUT – 200 (success)
           DELETE – 204 (success)
           Login မဝင်ထားရင်/token သက်တမ်းကုန်သွားရင် – 401 (unauthorized)
           Login ဝင်ပေမဲ့ permission မရှိရင် – 403 (forbidden)
           Model တွေကို ရှာမတွေ့ရင် – 404 (not found)
           Validation fail ရင် – 422 (unprocessable entity)
           Exception တွေဖမ်းရင် – 500 (internal server error)
  • Response တွေ(error response မဟုတ်ပါ)ကို data wrapper နဲ့သုံးပါမယ်။ ဒါကတော့နောက်ပိုင်း response data မှာ metadata တွေထည့်ချင်တဲ့သူတွေအတွက် အဆင်ပြေအောင်လုပ်ပေး
           တာပါ။ Laravel resource collection ဆိုလည်း data နဲ့ wrap ပါတယ်။ Pagination လုပ်ဖို့လိုအပ်လာလည်း အဆင်ပြေအောင်ပါ။ https://jsonapi.org/examples/ မှာ json api တစ်ခု
           အတွက် guideline ပေးထားတာ ကိုတွေ့ရပါတယ်။ သို့သော် ၎င်းမှာ အလွန်ရှုပ်ထွေးတယ်လို့ ထင်ပါတယ်။

{
  ” id “: 1
  “name”: “Kyaw Kyaw”
}

ဒီလို response အစား-

{
  ” data “: {
    ” id “: 1,
    ” name “: “Kyaw Kyaw”
  }
}

ဒီလို response ပြန်ပါမယ်။
Error တွေကို အောက်ပါအတိုင်း ပြန်ပါမယ်

{
“error” : {
    “status” : 502,
    “message” : “Bad gateway.”
  }
}

အထက်ဖော်ပြပါ အကြံပြုချက်တွေဟာ api ရော web URL အတွက်ပါအသုံးဝင်နိုင်မယ်လို့ ထင်ပါတယ်။ ဒါဟာမဖြစ်မနေလုပ်ရမယ်လို့ ဆိုလိုတာတော့မဟုတ်ပါဘူး။ သို့ပေမဲ့ ဒီအချက်လေးတွေကတော့ကျွန်တော်တို့ရဲ့ web app ကိုစနစ်တကျဖြစ်အောင် ကူညီပေးနိုင်မယ်လို့တော့ ထင်ပါတယ်။ ကျွန်တော်တို့ရဲ့ bookstore app အတွက် sample route တွေကို သတ်မှတ်ကြည့်ကြတာပေါ့ဗျာ။

Web app 
Base URL: bookstore.com
Action: member
/members GET Member အားလုံးဖော်ပြတဲ့ page
/members/create GET Member register လုပ်မဲ့ form
/members POST Member register လုပ်မဲ့ action
/members/edit GET Member profile ပြောင်းမဲ့ page
/members PUT Member profile update လုပ်မဲ့ action
/members/delete GET Member delete confirm form (optional)
/members DELETE Member delete လုပ်မဲ့ action

စာအုပ်၊ စာအုပ်ငှား/ပြန်အပ်တဲ့ route တွေဟာလည်းအပေါ်ကနည်းတူ သတ်မှတ်ပေးရင် အဆင်ပြေနိုင်ပါတယ်။

Web API 
Base URL: bookstore.com
Action: member (version 1)
/api/v1/members GET Member အားလုံးထုတ်တဲ့ URL
/api/v1/members POST Member register လုပ်မဲ့ action
/api/v1/members PUT Member profile update လုပ်မဲ့ action
/api/v1/members DELETE Member delete လုပ်မဲ့ action
/api/v1/members/deactivate POST Member ကို deactivate လုပ်လိုလျှင်

 

စာအုပ်ငှားမဲ့ action တွေ
Base URL: bookstore.com
/api/v1/books/borrow POST စာအုပ်အသစ်ငှားတဲ့ URL
/api/v1/books/return POST စာအုပ်လာအပ်တဲ့ URL
/api/v1/members/{id}/borrow GET Member တယောက်ငှားထားတဲ့ စာအုပ်စာရင်း
/api/v1/books/{id}/borrow GET စာအုပ်တအုပ်ရဲ့ အငှားစာရင်း
/api/v1/books/borrow GET လက်ရှိငှားထွက်ထားတဲ့ စာအုပ်စာရင်း

ဒီလောက်ဆိုရင် အကြမ်းဖျဉ်းသဘောကို နားလည်နိုင်ကြပါမယ်လို့ထင်ပါတယ်။ ထပ်ပြီးတော့ ဆွေးနွေးအကြံပြုချင်တာတွေရှိရင် ကျွန်တော့်မေးလ် (jordan.myoko@gmail.com) ကိုဆက်သွယ်ပြောဆိုနိုင်ပါတယ်ခင်ဗျာ။

စာကိုး –

https://nordicapis.com/best-practices-api-error-handling/
https://restfulapi.net/resource-naming/
https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/