REST API වල Errors හැන්ඩල් කරන විදිය – හැමදාම එක වගේ JSON Responses SC Guide

ආයුබෝවන්! කොහොමද කට්ටියට? අද අපි කතා කරන්න යන්නේ ඔයාලා හැමෝටම ගොඩක් වැදගත් වෙන, ඒ වගේම අපේ Software Engineering ජීවිතේදි නිතරම වගේ මුහුණ දෙන්න වෙන පොඩි ඒත් වැදගත් මාතෘකාවක් ගැන – ඒ තමයි REST API වල Error Handling.

ඔයාලා දන්නවද, අපි API එකක් හදනකොට, සාර්ථක (success) responses ගැන වගේම, වැරදි (error) responses ගැනත් හරියට හිතන්න ඕනේ කියලා? මොකද, මොන තරම් හොඳ API එකක් හැදුවත්, errors එන්න පුළුවන්. දත්ත නැති වෙන්න පුළුවන්, වැරදි input එන්න පුළුවන්, නැත්නම් අපිට පාලනය කරන්න බැරි server side errors එන්න පුළුවන්. මේ වගේ වෙලාවට අපේ API එකෙන් දෙන error message එක client එකට, ඒ කියන්නේ අපේ frontend එකට හෝ වෙනත් service එකකට කොයි තරම් පැහැදිලිද කියන එක ගොඩක් වැදගත්.

හිතන්නකෝ, ඔයාලා කෝඩ් කරනකොට එක වෙලාවකදී error message එකක් එනවා "Error: User not found" කියලා. තව වෙලාවක "The requested resource was not located" කියලා. තවත් වෙලාවකදී "statusCode": 404, "message": "Sorry, we couldn't find it" වගේ JSON එකක්. මේ වගේ විවිධ format වලින් errors එනකොට, frontend එකට මේවා handle කරන එක පුදුම headache එකක්. සමහරවිට frontend එකට error message එක display කරන්නත් බැරි වෙනවා.

අන්න ඒ නිසයි අපි අද කතා කරන්නේ REST API වල error responses standardize කරන්නේ කොහොමද කියලා. ඒ කියන්නේ, හැමදාම එකම විදියේ JSON format එකකින් errors return කරන්නේ කොහොමද කියලා. මේක කරන එකෙන් ඔයාලගේ API එක professional වෙනවා වගේම, ඒක පාවිච්චි කරන අයටත් ගොඩක් පහසුවක් වෙනවා. ඒ වගේම, debugging කරනකොටත් පුදුම විදියට වෙලාව ඉතුරු කරගන්න පුළුවන්. මේක හරියට, අපේ අම්මා හැමදාම හදන සම්බෝලෙ එකම රසට හැදුවා වගේ වැඩක්. අපි බලමු එහෙනම් මේක කොහොමද කරන්නේ කියලා!

1. ඇයි මේ Errors Standardize කරන්න ඕනේ? (Why Standardize Errors?)

දැන් ඔයාලා හිතනවා ඇති, මොකටද මේ හැම error එකක්ම එකම විදියට පෙන්නන්න යන්නේ කියලා. ඕනම දෙයක් හදනකොට, ඒක හරියට පිළිවෙළකට නැතිනම්, පස්සේ කාලෙකදී ලොකු ගැටලු එනවා. Errors වලදීත් එහෙමයි. අපි බලමු Standardized Error Responses නැතිනම් එන ප්‍රධාන ගැටලු ටිකක්.

• Frontend එකට Headache: ඔයාලගේ API එක පාවිච්චි කරන frontend developer ට හැම error response එකක්ම වෙන වෙනම handle කරන්න වෙනවා. එක වෙලාවක string එකක්, තව වෙලාවක object එකක්. මේකෙන් frontend code එක සංකීර්ණ වෙනවා වගේම, errors display කරන්න ගියොත් ඒවා ලස්සනට පෙන්වන්නත් බැරි වෙනවා.
• Debugging බරපතලයි: Error එකක් ආවම, ඒක කොහෙන්ද ආවේ, මොකක්ද හේතුව කියලා හොයාගන්න අමාරුයි. Error message එකේ හරියට විස්තරයක් නැතිනම්, server logs වලට ගිහින් බලන්න වෙනවා. මේකෙන් කාලය නාස්ති වෙනවා.
• API Clients වලට අපහසුයි: ඔයාලගේ API එක වෙන services හෝ third-party applications වලට පාවිච්චි කරනකොට, ඒ අයටත් මේ විවිධ error formats නිසා ගැටලු එනවා. ඔවුන්ටත් හැම error එකක්ම වෙන වෙනම parse කරන්න වෙනවා. මේකෙන් API එකේ usability එක අඩු වෙනවා.
• User Experience එකට බලපෑම: API එකෙන් එන errors පැහැදිලි නැතිනම්, අවසානයේදී මේක පාවිච්චි කරන user ටත් හොඳ අත්දැකීමක් ලැබෙන්නේ නැහැ. User ට තේරෙන්නේ නැහැ මොකක්ද වුණේ කියලා, නැත්නම් ඊළඟට මොකක්ද කරන්න ඕනේ කියලා.

ඉතින්, මේ ගැටලු නැති කරගන්න නම්, අපි හැම error response එකක්ම එකම විදියට, ඒ කියන්නේ standard format එකකින් return කරන්න ඕනේ. මේකෙන්:

• Predictability (අනාවැකිමය බව): Client එකට හැම වෙලේම බලාපොරොත්තු වෙන්න පුළුවන් error format එකක් ලැබෙනවා.
• Easier Debugging (පහසු Debugging): Error එකේ code එක, message එක, details වගේ දේවල් එක්ක ආවම, මොකක්ද වුණේ කියලා හොයාගන්න පහසුයි.
• Better User Experience (හොඳ User Experience): User ට පැහැදිලි error messages පෙන්වන්න පුළුවන්.
• Improved API Usability (වැඩිදියුණු වූ API භාවිතය): API එක පාවිච්චි කරන අයට ලේසියි.

අපි දැන් බලමු හොඳ Standard Error Response එකක අඩංගු වෙන්න ඕනේ ප්‍රධානම දේවල් මොනවද කියලා.

2. Standard Error Response එකක තියෙන්න ඕනේ මොනවද? (What should a Standard Error Response have?)

ලෝකේ ගොඩක් දෙනා පිළිගන්න, ඒ වගේම අපේ වැඩවලටත් ගොඩක් පහසු වෙන standard error response format එකක් අපි බලමු. මේකේදී අඩංගු විය යුතු ප්‍රධානම කොටස් ටිකක් තියෙනවා:

1. statusCode (HTTP Status Code): මේක ගොඩක්ම වැදගත්. REST API වලදී HTTP Status Codes පාවිච්චි කරන්නේ request එකේ තත්ත්වය කියන්න. Errors වලටත් ඒ වගේ codes තියෙනවා. උදාහරණයක් විදියට:මේ statusCode එක response headers වලත් තියෙනවා. ඒත් response body එකෙත් ඒක දාන එකෙන් client එකට ලේසියි ඒක access කරගන්න.
   • 400 Bad Request: Client එකෙන් දීපු input එක වැරදියි. (e.g., Required field missing, Invalid format)
   • 401 Unauthorized: Request එක authentication කරලා නැහැ. (e.g., No token, Invalid token)
   • 403 Forbidden: Authentication කරලා තිබ්බත්, මේ operation එක කරන්න අවසර නැහැ. (e.g., User doesn't have permissions)
   • 404 Not Found: ඉල්ලපු resource එක හොයාගන්න බැහැ. (e.g., User ID does not exist)
   • 409 Conflict: Request එක නිසා resource එකේ ගැටුමක් ඇති වෙනවා. (e.g., User with same email already exists)
   • 422 Unprocessable Entity: Request එකේදී යැවූ දත්ත වල ව්‍යාකරණමය දෝෂ නැතත්, අර්ථමය වශයෙන් සැකසීමට නොහැකි වීම. (e.g., Invalid business logic based on current state)
   • 500 Internal Server Error: Server එක ඇතුළේ අනපේක්ෂිත දෝෂයක්. (e.g., Database connection error, unhandled exception)
2. code (Custom Application Error Code): සමහර වෙලාවට HTTP Status Code එකෙන් විතරක් error එකේ ස්වභාවය හරියටම කියන්න බැරි වෙන්න පුළුවන්. ඒ වගේ වෙලාවට අපිට custom error codes පාවිච්චි කරන්න පුළුවන්. උදාහරණයක් විදියට, USER_NOT_FOUND, INVALID_EMAIL_FORMAT, PRODUCT_OUT_OF_STOCK වගේ codes පාවිච්චි කරන්න පුළුවන්. මේවා Unique වෙන්න ඕනේ, ඒ වගේම descriptive වෙන්නත් ඕනේ.
3. message (Human-Readable Message): User ට හෝ client developer ට තේරෙන විදියට ලියපු පොඩි error message එකක්. මේකෙන් error එක මොකක්ද කියලා පැහැදිලි කරන්න ඕනේ. "User with provided ID not found.", "Invalid email address provided." වගේ messages.
4. details or errors (Specific Error Details): මේක validation errors වගේ දේවල් වලට ගොඩක් වැදගත් වෙනවා. උදාහරණයක් විදියට, form එකක fields කිහිපයකම වැරදි තිබ්බොත්, ඒ හැම field එකකටම වෙන වෙනම error message එකක් මේකේ අඩංගු කරන්න පුළුවන්. මේක array එකක් හෝ object එකක් වෙන්න පුළුවන්. එක object එකක් තුළ වැරදි field එකේ නම (e.g., "field": "email") සහ ඒකට අදාළ error message එක (e.g., "message": "Email is required") වගේ දේවල් දාන්න පුළුවන්.
5. traceId (Optional, for Debugging): Server එකේ log එකක මේ error එකට අදාළ entry එක හොයාගන්න පුළුවන් Unique ID එකක්. Production environment එකේදී user ට හෝ client එකට මේක පෙන්වලා, ඒක Support team එකට දුන්නම, එයාලට logs වලින් මේ error එක හොයාගන්න ලේසියි.

මේවා තමයි ප්‍රධානම කොටස්. දැන් අපි බලමු මේවා පාවිච්චි කරලා කොහොමද error responses හදන්නේ කියලා.

3. Practical Implementation: කොහොමද API වල මේ Format එක පාවිච්චි කරන්නේ? (Practical Implementation: How to use this Format in APIs?)

අපි දැන් මේ උඩින් කතා කරපු structure එක පාවිච්චි කරලා, විවිධ error scenarios වලට කොහොමද JSON responses හදන්නේ කියලා බලමු. මේවා ඕනෑම programing language එකකින් හෝ framework එකකින් implement කරන්න පුළුවන්. වැදගත් වෙන්නේ response format එක standardize කරන එක.

Scenario 1: Validation Error (400 Bad Request)

හිතන්න, ඔයාලා user register කරන API එකක් හදනවා කියලා. ඒකට name, email, password වගේ fields ඕනේ. User කෙනෙක් request එකේදී name එක නැතුව යැව්වොත්, email එක වැරදි format එකකින් යැව්වොත්, ඒ වගේ දේවල් වලට 400 Bad Request එකක් දෙන්න පුළුවන්.

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "message": "One or more input fields are invalid.",
  "details": [
    {
      "field": "name",
      "message": "Name is required."
    },
    {
      "field": "email",
      "message": "Invalid email format."
    }
  ],
  "path": "/api/v1/users/register"
}

මේ response එකෙන් client එකට පැහැදිලිව පේනවා මොන fields වලද වැරදි තියෙන්නේ කියලා. ඒ වගේම, backend එකෙන් ආපු error code එකත් තියෙනවා VALIDATION_ERROR කියලා. මේකෙන් frontend එකට පුළුවන්, හරියටම මොන field එකටද error message එක display කරන්න ඕනේ කියලා identify කරගන්න.

Scenario 2: Resource Not Found (404 Not Found)

දැන් හිතන්න, ඔයාලා /api/v1/users/{userId} කියන endpoint එකට request එකක් යවනවා කියලා user details ගන්න. ඒත් userId එකෙන් user කෙනෙක් නැතිනම්, 404 Not Found response එකක් දෙන්න පුළුවන්.

{
  "statusCode": 404,
  "code": "USER_NOT_FOUND",
  "message": "The user with the provided ID was not found.",
  "path": "/api/v1/users/12345"
}

මේක සාමාන්‍ය 404 Not Found HTML page එකකට වඩා ගොඩක් හොඳයි. Client එකට හරියටම දන්නවා මොකක්ද වුණේ කියලා.

Scenario 3: Internal Server Error (500 Internal Server Error)

සමහර වෙලාවට අපිට පාලනය කරන්න බැරි, අපේ code එකේ නොහිතපු bug එකක් නිසා හෝ database connection එකේ ගැටලුවක් නිසා server එකේ error එකක් එන්න පුළුවන්. මේ වගේ වෙලාවට 500 Internal Server Error එකක් දෙන්න ඕනේ. ඒත් මේකේදී sensitive information (stack traces වගේ) client එකට යවන්න එපා. ඒ වෙනුවට, unique traceId එකක් යවලා, ඒක අපේ server logs වල check කරන්න පුළුවන් වෙන්න ඕනේ.

{
  "statusCode": 500,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred on the server. Please try again later.",
  "traceId": "abcd-1234-efgh-5678",
  "path": "/api/v1/products/create"
}

මේ traceId එක ගැන client එකට කියන්න පුළුවන්, මේක Support team එකට දෙන්න කියලා. එතකොට එයාලට පුළුවන් මේ ID එකෙන් logs වල හරියටම error එකේ විස්තර හොයාගන්න.

Scenario 4: Unauthorized or Forbidden (401 / 403)

Authentication හෝ Authorization errors වලටත් මේ format එක පාවිච්චි කරන්න පුළුවන්.

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Authentication required. Please provide a valid token."
}

{
  "statusCode": 403,
  "code": "FORBIDDEN",
  "message": "You do not have sufficient permissions to perform this action."
}

4. Implement කරද්දී මතක තියාගන්න දේවල් (Things to remember when implementing)

මේ error handling standard එක implement කරනකොට මතක තියාගන්න ඕනේ වැදගත් කරුණු කිහිපයක් තියෙනවා:

• Centralized Error Handling (මධ්‍යගත Error Handling): ඔයාලගේ API එකේ හැම endpoint එකකම error handle කරන්නේ නැතුව, centralized error handling mechanism එකක් හදන්න. මේක middleware එකක්, exception filter එකක් හෝ global error handler එකක් වෙන්න පුළුවන්. මේකෙන් පුළුවන් හැම error එකක්ම අර standard format එකට convert කරලා client එකට යවන්න. මේකෙන් code duplication එක අඩු වෙනවා වගේම, consistency එකත් සහතික කරනවා.
• Custom Exception Classes (Custom Exception Classes): Programming language එකේ තියෙන built-in exception classes වලට අමතරව, ඔයාලට පුළුවන් custom exception classes හදාගන්න. උදාහරණයක් විදියට UserNotFoundException, InvalidInputException වගේ දේවල්. මේවාට පුළුවන් තමන්ට අදාළ statusCode, code, message වගේ දේවල් අරගෙන යන්න. එතකොට central error handler එකට මේ exception type එක අනුව response එක generate කරන්න පුළුවන්.
• Don't Expose Sensitive Information (Sensitive Information එළියට දාන්න එපා): 500 Internal Server Error වගේ දේවල් වලදී කිසිම වෙලාවක database credentials, server paths, stack traces වගේ sensitive information client එකට යවන්න එපා. ඒ වෙනුවට generic message එකක් සහ traceId එකක් වගේ දෙයක් යවන්න.
• Consistency is Key (Consistency තමයි ප්‍රධාන): ඔයාලා තෝරාගන්න error format එක හැමදාම, ඔයාලගේ API එකේ හැම endpoint එකකම use කරන්න ඕනේ. එතකොට තමයි API එකේ usability එක උපරිම වෙන්නේ.
• Documentation (Documentation): ඔයාලගේ API documentation එකේ (e.g., Swagger/OpenAPI) මේ error response formats ගැන පැහැදිලිව සඳහන් කරන්න. එතකොට API එක පාවිච්චි කරන අයට මේවා ගැන ඉස්සරහටම දැනගන්න පුළුවන්.

5. අනුරාධනයක්: API එකට මේ "බඩුවක්" දෙන්න (Try This to Your API)

ඉතින්, අපි අද කතා කළා REST API වල error handling කොයි තරම් වැදගත්ද, ඒ වගේම ඒක standardize කරන්නේ කොහොමද කියලා. මේ ක්‍රමවේදයන් පාවිච්චි කරන එකෙන් ඔයාලගේ API එක වෘත්තීය මට්ටමට ගේන්න පුළුවන් වගේම, debugging වලට වැය වෙන කාලයත් ගොඩක් අඩු කරගන්න පුළුවන්.

මේ වගේ පිළිවෙලකට errors handle කරන එකෙන්, ඔයාලා frontend developer කෙනෙක් නම්, ඔයාලට පහසුවෙන් error messages display කරන්න පුළුවන්. Backend developer කෙනෙක් නම්, server logs වල error trace කරගන්න ලේසියි. ඒ වගේම අවසානයේදී, මේක පාවිච්චි කරන user ටත් හොඳ අත්දැකීමක් ලැබෙනවා. මේක හරියට, අවුල් වෙලා තිබ්බ මේසයක් පිළිවෙලකට හැදුවා වගේ වැඩක්.

ඔයාලගේ අදහස් පහළින් comment කරන්න අමතක කරන්න එපා! ඔයාලා මේ වෙනකොට මේ වගේ error handling practices පාවිච්චි කරනවද? නැත්නම් වෙනස් විදියකටද කරන්නේ? ඔයාලගේ අත්දැකීම් බෙදාගන්න. ඒ වගේම, මේ ලිපියේ තියෙන concepts අරගෙන, ඔයාලගේම API එකක පොඩි experiment එකක් කරලා බලන්න. ඒකෙන් ඔයාලට මේකේ වටිනාකම තවත් හොඳට තේරේවි.

ඊළඟ ලිපියෙන් හම්බවෙනකම්, සුබ කෝඩින්ග්!