03.08 Naming Convention

---

📌 At a Glance

รายการ	รายละเอียด
Topic	Naming Convention
Difficulty	⭐ Beginner
Reading Time	5 นาที
Target	Developer, API Designer

---

🎯 Learning Objectives

หลังจากศึกษาหัวข้อนี้แล้ว ผู้อ่านจะสามารถ

• เข้าใจมาตรฐานการตั้งชื่อของ SISAHYGO API
• ตั้งชื่อ Endpoint ได้อย่างถูกต้อง
• เข้าใจรูปแบบ Field Name และ JSON Property
• พัฒนา API ใหม่ให้สอดคล้องกับมาตรฐานของระบบ

---

Overview

SISAHYGO API ใช้มาตรฐานการตั้งชื่อเดียวกันทุก Endpoint เพื่อให้การใช้งานมีความสม่ำเสมอ อ่านง่าย และลดความสับสนในการพัฒนา

มาตรฐานนี้ครอบคลุม

• URL Endpoint
• Resource Name
• JSON Field
• Parameter
• Response Field

---

Figure 3-8 Naming Convention

(แทรกรูป Figure 3-8 : Naming Convention Reference)

Figure 3-8 สรุปหลักการตั้งชื่อของ SISAHYGO API ทั้งในส่วนของ URL, Resource, JSON Field และ Query Parameters เพื่อให้ทุก Endpoint มีรูปแบบเดียวกัน

---

URL Convention

ใช้

• ตัวพิมพ์เล็ก (lowercase)
• คั่นคำด้วยเครื่องหมาย - (kebab-case)
• ใช้คำนามพหูพจน์ (Plural Nouns)

ตัวอย่าง

Resource	Endpoint
Products	/products
Receivers	/receivers
Order Checkings	/order-checkings
Shipments	/shipments
Order Rejections	/order-rejections

---

JSON Field Convention

Field Name ใช้รูปแบบ snake_case

ตัวอย่าง

{
    "reference_no": "SO2026000123",
    "receiver_code": "RCV0001",
    "payment_type": "H",
    "product_code": "P0001"
}

---

Query Parameter Convention

ใช้ snake_case เช่นเดียวกับ JSON

ตัวอย่าง

GET /api/v1/shipments?reference_no=SO2026000123

หรือ

GET /api/v1/order-rejections?reference_no=SO2026000123

---

Naming Rules

Item	Convention	Example
Endpoint	kebab-case	/order-checkings
JSON Field	snake_case	reference_no
Query Parameter	snake_case	receiver_code
Enum Value	UPPERCASE หรือ Code ตามที่กำหนด	H, T, E
Boolean	true / false	success: true

---

Reserved Words

ไม่ควรใช้ชื่อที่มีความหมายกำกวม เช่น

• data
• value
• object
• temp
• test
• info

ควรใช้ชื่อที่สื่อความหมายตรงกับข้อมูล เช่น

• product_code
• receiver_code
• shipment_status
• reference_no

---

Key Points

Item	Standard
URL	kebab-case
JSON	snake_case
Parameters	snake_case
Encoding	UTF-8
Language	English

---

Implementation Notes

• Endpoint ทุกตัวใช้ภาษาอังกฤษ
• ใช้ชื่อเดียวกันทั้ง Request และ Response หากอ้างถึงข้อมูลเดียวกัน
• หลีกเลี่ยงการย่อคำที่ไม่เป็นมาตรฐาน
• หากเพิ่ม Resource ใหม่ ให้ใช้รูปแบบเดียวกับ API เดิม

---

Best Practices

• ใช้ชื่อที่สื่อความหมายชัดเจน
• ใช้มาตรฐานเดียวทั้งระบบ
• หลีกเลี่ยงการเปลี่ยนชื่อ Field หลังเผยแพร่ API
• รักษา Backward Compatibility เมื่อมีการเพิ่ม Field ใหม่

---

Summary

การใช้ Naming Convention เดียวกันทุก Endpoint ช่วยให้ SISAHYGO API มีความสม่ำเสมอ เรียนรู้ได้ง่าย และลดข้อผิดพลาดในการพัฒนาและบำรุงรักษาระบบ

---

Next Step

➡️ 03.09 Error Response Standard