การออกแบบ API สาธารณะสำหรับผู้สร้าง SaaS ครั้งแรก: พื้นฐาน

ปัญหาจริง: ส่งมอบ API ที่คุณดูแลรักษาได้

API สาธารณะไม่ใช่แค่ endpoint ที่แอปของคุณเปิดออก มันคือสัญญาที่ให้กับคนนอกทีมว่าข้อตกลงจะยังใช้งานได้ แม้คุณจะเปลี่ยนผลิตภัณฑ์

ส่วนยากไม่ใช่การเขียน v1 แต่คือการรักษาเสถียรภาพขณะคุณแก้บั๊ก เพิ่มฟีเจอร์ และเรียนรู้ว่าลูกค้าต้องการอะไรจริงๆ

การตัดสินใจแต่แรกจะโผล่เป็นข้อความ support ในภายหลัง หากการตอบกลับเปลี่ยนรูปแบบโดยไม่มีการแจ้ง หากการตั้งชื่อไม่สอดคล้อง หรือถ้าฝั่งไคลเอนต์ไม่รู้ว่าคำขอสำเร็จหรือไม่ คุณสร้างแรงเสียดทาน แรงเสียดทานนั้นกลายเป็นความไม่ไว้วางใจ และความไม่ไว้วางใจทำให้คนหยุดสร้างบนแพลตฟอร์มของคุณ

ความเร็วก็สำคัญเช่นกัน ผู้สร้าง SaaS ครั้งแรกส่วนใหญ่ต้องส่งบางอย่างที่ใช้งานได้เร็ว แล้วค่อยปรับปรุง ข้อแลกเปลี่ยนง่าย ๆ คือ: ยิ่งส่งเร็วโดยไม่มีกฎมากเท่าไหร่ คุณจะยิ่งใช้เวลามากขึ้นในการย้อนคืนการตัดสินใจเหล่านั้นเมื่อผู้ใช้จริงมาถึง

สำหรับ v1 ที่พอใช้ได้มักหมายถึงชุด endpoint เล็ก ๆ ที่แมปกับการกระทำของผู้ใช้จริง การตั้งชื่อและรูปแบบการตอบกลับคงที่ กลยุทธ์การเปลี่ยนแปลงที่ชัดเจน (แม้แค่ v1) การแบ่งหน้าที่คาดเดาได้ ขีดจำกัดอัตราที่สมเหตุสมผล และเอกสารที่โชว์ชัดว่าต้องส่งอะไรและจะได้อะไรกลับมา

ตัวอย่างเป็นรูปธรรม: สมมติว่าลูกค้าสร้างการผสานที่สร้างใบแจ้งหนี้ทุกคืน หากคุณเปลี่ยนชื่อฟิลด์ เปลี่ยนรูปแบบวันที่ หรือเริ่มส่งผลลัพธ์บางส่วนโดยเงียบ งานของพวกเขาจะล้มเหลวตอนตี 2 พวกเขาจะโทษ API ของคุณ ไม่ใช่โค้ดของพวกเขา

ถ้าคุณสร้างด้วยเครื่องมือแชทอย่าง Koder.ai มันอาจทำให้คุณสร้าง endpoint ได้เร็วมาก นั่นไม่เป็นไร แต่เก็บพื้นผิวสาธารณะให้เล็ก คุณสามารถเก็บ endpoint ภายในเป็นส่วนตัวในช่วงเรียนรู้ว่าอะไรควรเป็นสัญญาระยะยาว

เริ่มจากพื้นผิว API เล็ก ๆ และชัดเจน

การออกแบบ API สาธารณะที่ดีเริ่มจากการเลือกชุดคำนาม (resources) เล็ก ๆ ที่ตรงกับภาษาที่ลูกค้าใช้พูดถึงผลิตภัณฑ์ของคุณ รักษาชื่อทรัพยากรให้คงที่แม้ฐานข้อมูลภายในจะเปลี่ยน เมื่อคุณเพิ่มฟีเจอร์ ให้เพิ่มฟิลด์หรือ endpoint ใหม่แทนการเปลี่ยนชื่อทรัพยากรหลัก

ชุดเริ่มต้นที่ใช้งานได้จริงสำหรับหลายผลิตภัณฑ์ SaaS คือ: users, organizations, projects และ events หากคุณอธิบายทรัพยากรไม่ได้ในหนึ่งประโยค มันค่อนข้างยังไม่พร้อมที่จะเป็นสาธารณะ

ทำให้การใช้งาน HTTP น่าเบื่อและคาดเดาได้:

• GET อ่านข้อมูล (ไม่มีผลข้างเคียง)
• POST สร้างบางอย่าง (หรือเริ่มการกระทำ)
• PATCH อัพเดตเพียงบางฟิลด์
• DELETE ลบหรือปิดการใช้งานบางอย่าง

การยืนยันตัวตนในวันแรกไม่จำเป็นต้องซับซ้อน หาก API ของคุณเป็น server-to-server เป็นหลัก (ลูกค้าเรียกจาก backend ของพวกเขา) API keys มักพอเพียง หากลูกค้าจำเป็นต้องทำในฐานะผู้ใช้ปลายทาง หรือคุณคาดหวังการผสานจาก third-party ที่ผู้ใช้ให้สิทธิ OAuth มักเป็นตัวเลือกที่เหมาะกว่า เขียนการตัดสินใจด้วยภาษาง่าย ๆ: ใครเป็นผู้เรียก และพวกเขาสามารถเข้าถึงข้อมูลของใครบ้าง?

ตั้งความคาดหวังแต่แรก อธิบายชัดเจนว่าสิ่งใดเป็นสิ่งที่รองรับและสิ่งใดเป็นความพยายามที่ดีที่สุด ตัวอย่าง: endpoints แบบ list เสถียรและเข้ากันย้อนหลังได้ แต่ search filters อาจขยายและไม่รับประกันว่าจะครอบคลุมทั้งหมด สิ่งนี้ลดการติดต่อ support และปล่อยคุณให้ปรับปรุงต่อได้

ถ้าคุณสร้างบนแพลตฟอร์มอย่าง Koder.ai ให้ปฏิบัติต่อ API เป็นสัญญาผลิตภัณฑ์: ทำสัญญาให้เล็กก่อน แล้วขยายตามการใช้งานจริง ไม่ใช่การเดา

การเวอร์ชันโดยไม่ติดกับมุม

การเวอร์ชันเกี่ยวกับความคาดหวังเป็นหลัก ลูกค้าต้องการรู้: การผสานของฉันจะพังสัปดาห์หน้าไหม? คุณต้องการพื้นที่ปรับปรุงโดยไม่ต้องกลัว

การเวอร์ชันใน URL เทียบกับใน header

การเวอร์ชันผ่าน header อาจดูสะอาด แต่ซ่อนง่ายจาก logs, caches และภาพหน้าจอการสนับสนุน การเวอร์ชันใน URL มักเป็นตัวเลือกที่ง่ายที่สุด: /v1/... เมื่อมีคำขอที่ล้มเหลว ลูกค้าส่งมาให้คุณดูคุณจะเห็นเวอร์ชันทันที และยังทำให้รัน v1 กับ v2 เคียงข้างกันได้ง่าย

การเปลี่ยนแปลงแบบ breaking จริง ๆ คืออะไร

การเปลี่ยนแปลงถือเป็น breaking ถ้า client ที่ทำตามกฎอาจหยุดทำงานโดยไม่ต้องเปลี่ยนโค้ด ตัวอย่างทั่วไป:

• เปลี่ยนชื่อฟิลด์ (เช่น customer_id เป็น customerId)
• เปลี่ยนประเภทฟิลด์ (จาก string เป็น number) หรือความหมายของมัน
• เอา endpoint หรือฟิลด์ในการตอบกลับที่ลูกค้าอาจพึ่งพาออก
• ทำให้กฎการ validate เข้มงวดขึ้น (จาก optional เป็น required)
• เปลี่ยนข้อกำหนด auth หรือสิทธิ์เริ่มต้น

การเปลี่ยนแปลงที่ปลอดภัยคือการที่ client เก่ายังไม่ต้องสนใจมันได้ การเพิ่มฟิลด์ optional ใหม่มักปลอดภัย เช่น การเพิ่ม plan_name ในการตอบ GET /v1/subscriptions มักไม่ทำให้ client ที่อ่านแค่ status พัง

กฎปฏิบัติ: อย่าเอาหรือใช้ฟิลด์ใหม่ในเวอร์ชันหลักเดียวกัน แทนที่จะทำอย่างนั้น ให้เพิ่มฟิลด์ เก็บของเดิมไว้ และเก็บไว้จนกว่าคุณจะพร้อมเลิกใช้ทั้งเวอร์ชัน

นโยบายการเลิกใช้ที่ทำตามได้

ทำให้เรียบง่าย: ประกาศการเลิกใช้แต่เนิ่น ๆ คืนข้อความเตือนใน response ให้ชัด และกำหนดวันสิ้นสุด สำหรับ API แรก หน้าต่าง 90 วัน มักเป็นไปได้ ในช่วงเวลานั้น ให้รักษา v1 ไว้ ทำโน้ตการย้ายสั้น ๆ และให้ support ชี้ไปยังบรรทัดเดียว: v1 ใช้ได้จนถึงวันที่นี้; นี่คือความเปลี่ยนแปลงใน v2

ถ้าคุณสร้างบนแพลตฟอร์มอย่าง Koder.ai ให้คิดว่าเวอร์ชันเป็น snapshot: ปล่อยการปรับปรุงในเวอร์ชันใหม่ รักษาเวอร์ชันเก่าให้เสถียร และตัดทิ้งก็ต่อเมื่อคุณให้เวลาลูกค้าพอที่จะย้ายแล้ว

รูปแบบการแบ่งหน้าที่คงเดิม

การแบ่งหน้าเป็นที่ที่ความไว้วางใจถูกชนะหรือแพ้ หากผลลัพธ์กระโดดไปมาระหว่างคำขอ ผู้ใช้จะหยุดเชื่อถือ API ของคุณ

ใช้ page/limit เมื่อชุดข้อมูลเล็ก คำค้นง่าย และผู้ใช้มักต้องการหน้า 3 จาก 20 ใช้ cursor-based เมื่อรายการเติบโตมาก มีรายการใหม่บ่อย หรือผู้ใช้สามารถเรียงและกรองเยอะ การแบ่งหน้าแบบ cursor ทำให้ลำดับคงที่แม้ว่าจะมีเรคคอร์ดใหม่เข้ามา

กฎไม่กี่ข้อช่วยให้การแบ่งหน้าน่าเชื่อถือ:

• กำหนดการเรียงลำดับเริ่มต้นเสมอ (เช่น: created_at desc)
• เพิ่ม tie-breaker (เช่น: id) เพื่อให้ลำดับกำหนดได้
• มองการแบ่งหน้าเป็นส่วนหนึ่งของสัญญา: การเปลี่ยนการเรียงในภายหลังเป็น breaking change
• คืนข้อมูลขั้นต่ำที่ต้องใช้ต่อ: items บวก next cursor (หรือ next page)

การนับผลรวม (totals) มักมีปัญหา total_count อาจแพงบนตารางใหญ่ โดยเฉพาะกับ filters หากให้ได้อย่างถูกและถูกต้อง ให้รวมมัน หากทำไม่ได้ ให้ตัดออกหรือทำให้เป็นตัวเลือกผ่าน query flag

ตัวอย่างรูปร่างคำขอ/การตอบกลับง่าย ๆ

// Page/limit
GET /v1/invoices?page=2\u0026limit=25\u0026sort=created_at_desc

{
  "items": [{"id":"inv_1"},{"id":"inv_2"}],
  "page": 2,
  "limit": 25,
  "total_count": 142
}

// Cursor-based
GET /v1/invoices?limit=25\u0026cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wOVQxMDozMDowMFoiLCJpZCI6Imludl8xMDAifQ==

{
  "items": [{"id":"inv_101"},{"id":"inv_102"}],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wOVQxMDoyNTowMFoiLCJpZCI6Imludl8xMjUifQ=="
}

Rate limits และการลองใหม่อย่างสุภาพ

Rate limits ไม่ได้เกี่ยวกับความเข้มงวดเท่านั้น แต่เกี่ยวกับการออนไลน์ให้อยู่ได้ พวกมันปกป้องแอปของคุณจากการระเบิดของทราฟิก ปกป้องฐานข้อมูลจากคิวรีที่แพงเกินไป และปกป้องบิลโครงสร้างพื้นฐานของคุณ ขีดจำกัดยังเป็นสัญญาด้วย: ลูกค้ารู้ว่าการใช้งานปกติเป็นอย่างไร

เริ่มเรียบง่ายแล้วปรับแต่งทีหลัง เลือกค่าที่ครอบคลุมการใช้งานทั่วไปพร้อมพื้นที่ให้กระชากสั้น ๆ แล้วดูทราฟิกจริง หากยังไม่มีข้อมูล ค่าเริ่มต้นที่ปลอดภัยคือขีดจำกัดต่อ API key เช่น 60 คำขอต่อนาทีพร้อม burst เล็ก ๆ หาก endpoint ใดหนักกว่า (เช่น search หรือ exports) ให้กำหนดขีดจำกัดเข้มงวดกว่า หรือกฎค่าใช้จ่ายแยกต่างหาก แทนที่จะลงโทษทุกคำขอ

เมื่อคุณบังคับใช้ขีดจำกัด ให้ทำให้ลูกค้าทำสิ่งที่ถูกต้องได้ง่าย คืน 429 Too Many Requests และใส่ headers มาตรฐานบางตัว:

• X-RateLimit-Limit: จำนวนสูงสุดที่อนุญาตในหน้าต่าง
• X-RateLimit-Remaining: เหลืออีกกี่คำขอ
• X-RateLimit-Reset: เมื่อหน้าต่างรีเซ็ต (timestamp หรือวินาที)
• Retry-After: ต้องรอนานเท่าใดก่อนลองใหม่

ลูกค้าควรถือ 429 เป็นสถานะปกติ ไม่ใช่ความผิดพลาดที่ต้องสู้ รูปแบบการลองใหม่อย่างสุภาพช่วยให้ทั้งสองฝ่ายมีความสุข:

• รอ Retry-After เมื่อตัวมันมี
• หากไม่มี ใช้ exponential backoff (เช่น 1s, 2s, 4s)
• เพิ่มความสุ่มเล็กน้อย (jitter) เพื่อไม่ให้ลูกค้าหลายรายลองใหม่พร้อมกัน
• จำกัดเวลารอสูงสุด (เช่น 30–60s)

ตัวอย่าง: ถ้าลูกค้ารันการซิงก์ประจำคืนที่กระแทก API ของคุณหนัก งานของพวกเขาสามารถกระจายคำขอในหนึ่งนาทีและชะลออัตโนมัติเมื่อเจอ 429 แทนการล้มทั้งงาน

ข้อผิดพลาด รหัสสถานะ และการเขียนที่ปลอดภัย

ถ้าข้อความ error ของคุณอ่านยาก กระทู้ support จะพอกพูนอย่างรวดเร็ว เลือกรูปแบบ error เดียวแล้วยึดมันทั่วทั้งระบบ รวมทั้ง 500 รูปแบบมาตรฐานง่าย ๆ คือ: code, message, details, และ request_id ให้ผู้ใช้คัดวางในแชท support ได้

ตัวอย่างรูปแบบเล็ก ๆ และคาดเดาได้:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid.",
    "details": {
      "fields": [
        {"name": "email", "issue": "must be a valid email"},
        {"name": "plan", "issue": "must be one of: free, pro, business"}
      ]
    },
    "request_id": "req_01HT..."
  }
}

ใช้ HTTP status codes แบบเดียวกันทุกครั้ง: 400 สำหรับ input ผิดพลาด, 401 เมื่อตัว auth หายหรือไม่ถูกต้อง, 403 เมื่อล็อกอินแล้วแต่ไม่มีสิทธิ์, 404 เมื่อไม่พบทรัพยากร, 409 สำหรับความขัดแย้ง (เช่น ค่าที่ต้องเป็นเอกลักษณ์ซ้ำหรือสถานะไม่ถูกต้อง), 429 สำหรับ rate limits, และ 500 สำหรับข้อผิดพลาดของเซิร์ฟเวอร์ ความสม่ำเสมอชนะความฉลาด

ทำให้ข้อผิดพลาดในการ validate แก้ได้ง่าย คำแนะนำระดับฟิลด์ควรชี้พารามิเตอร์ตามชื่อที่คุณใช้ในเอกสาร ไม่ใช่คอลัมน์ฐานข้อมูลภายใน หากมีข้อกำหนดรูปแบบ (วันที่ สกุลเงิน enum) บอกว่าคุณรับอะไรและยกตัวอย่าง

การลองใหม่เป็นจุดที่หลาย API เผลอสร้างข้อมูลซ้ำ สำหรับ POST สำคัญ (การชำระเงิน การสร้างใบแจ้งหนี้ การส่งอีเมล) รองรับ idempotency keys เพื่อให้ลูกค้าลองใหม่ได้อย่างปลอดภัย

• ยอมรับ header Idempotency-Key ในบาง POST endpoints ที่เลือก
• เก็บคีย์พร้อมผลลัพธ์ไว้ช่วงเวลาสั้น ๆ (เช่น 24 ชั่วโมง)
• เมื่อได้คีย์ซ้ำ ให้คืนการตอบกลับเหมือนคำขอแรก
• ถ้าคำขอแรกยังประมวลผลอยู่ ให้คืนการตอบชัดเจนว่าลองใหม่ทีหลังแทนการสร้างทรัพยากรซ้ำ

Header เดียวนี้ป้องกันกรณีขอบที่เจ็บปวดเมื่อเครือข่ายไม่เสถียรหรือไคลเอนต์โดน timeout

สถานการณ์ตัวอย่าง: SaaS บิลลิ่งเล็ก ๆ ในการใช้งานจริง

สมมติว่าคุณรัน SaaS ง่าย ๆ ที่มีวัตถุหลักสามตัว: projects, users, และ invoices โปรเจกต์มีผู้ใช้หลายคน และแต่ละโปรเจกต์ได้รับใบแจ้งหนี้รายเดือน ลูกค้าต้องการซิงก์ใบแจ้งหนี้เข้ากับเครื่องมือบัญชีของพวกเขาและแสดงบิลลิ่งพื้นฐานในแอปของตัวเอง

v1 ที่สะอาดอาจดูแบบนี้:

GET  /v1/projects/{project_id}
GET  /v1/projects/{project_id}/invoices
POST /v1/projects/{project_id}/invoices

ตอนนี้เกิดการเปลี่ยนแปลงแบบ breaking ขึ้น ใน v1 คุณเก็บจำนวนเงินของใบแจ้งหนี้เป็น integer ในหน่วยเซ็นต์: amount_cents: 1299 ต่อมา คุณต้องการรองรับหลายสกุลเงินและทศนิยม ดังนั้นคุณอยากได้ amount: "12.99" และ currency: "USD" หากคุณเขียนทับฟิลด์เก่า การผสานเดิมทั้งหมดจะพัง เวอร์ชันช่วยหลีกเลี่ยงความตื่นตระหนก: รักษา v1 ให้เสถียร ปล่อย /v2/... กับฟิลด์ใหม่ และรองรับทั้งสองจนกว่าลูกค้าจะย้าย

สำหรับการลิสต์ใบแจ้งหนี้ ให้ใช้รูปแบบแบ่งหน้าที่คาดเดาได้ ตัวอย่าง:

GET /v1/projects/p_123/invoices?limit=50\u0026cursor=eyJpZCI6Imludl85OTkifQ==

200 OK
{
  "data": [ {"id":"inv_1001"}, {"id":"inv_1000"} ],
  "next_cursor": "eyJpZCI6Imludl8xMDAwIn0="
}

วันหนึ่งลูกค้านำเข้าใบแจ้งหนี้เป็นลูปและโดน rate limit แทนที่จะได้ความล้มเหลวแบบสุ่ม พวกเขาจะได้รับการตอบชัดเจน:

• 429 Too Many Requests
• Retry-After: 20
• body error เล็ก ๆ เช่น { "error": { "code": "rate_limited" } }

ฝั่งลูกค้าสามารถหยุดพัก 20 วินาที แล้วทำต่อจาก cursor เดิมโดยไม่ต้องดาวน์โหลดซ้ำทั้งหมดหรือสร้างใบแจ้งหนี้ซ้ำ

ขั้นตอนทีละขั้น: แผนการปล่อย v1 ง่าย ๆ ของคุณ

การปล่อย v1 จะดีกว่าถ้าคุณปฏิบัติต่อมันเป็นการปล่อยผลิตภัณฑ์ขนาดเล็ก ไม่ใช่กอง endpoint เป้าหมายคือเรียบง่าย: คนสามารถสร้างบนมัน และคุณสามารถปรับปรุงต่อได้โดยไม่มีเซอร์ไพรส์

แผนปฏิบัติการ 1 สัปดาห์ (แม้สำหรับทีมเล็ก)

เริ่มจากเขียนหนึ่งหน้าอธิบายว่า API ของคุณมีไว้ทำอะไรและไม่ใช่อะไร เก็บพื้นผิวให้เล็กพอที่คุณจะอธิบายออกเสียงได้ในหนึ่งนาที

ใช้ลำดับนี้และอย่าไปขั้นต่อไปจนกว่าแต่ละขั้นจะพอใช้ได้:

1. ร่างสเปกหน้าเดียวที่ตั้งชื่อทรัพยากรหลักและ 5–10 endpoints แรกที่คุณจะสนับสนุน รวมรูปแบบ base URL, วิธี auth, และ headers ที่ต้องการ
2. สำหรับทุก endpoint เขียนคำขอจริงและการตอบกลับจริงหนึ่งรายการ ใช้ชื่อฟิลด์จริงที่คุณจะปล่อย ตัวอย่างเหล่านี้จะเป็นเอกสารแรกและเทสต์แรกของคุณ
3. เพิ่มส่วนกฎสั้น ๆ: ข้อความ error เป็นอย่างไร การแบ่งหน้าเป็นอย่างไร (ถ้ามี list endpoint) ขีดจำกัดเป็นอย่างไร และฟิลด์ใดเสถียรเทียบกับที่อาจเปลี่ยน
4. ทดสอบภายในด้วย fake client แกล้งทำเป็นลูกค้า สร้าง integration ใน repo ใหม่ เวลาในการเรียกแรกสำเร็จและจดจุดที่สับสน
5. เผยแพร่สัญญา v1: การเปลี่ยนแปลงใดปลอดภัย (ฟิลด์เพิ่มแบบ additive), การเปลี่ยนแปลงใดต้องเวอร์ชันใหม่, และคุณจะให้เวลาแจ้งเท่าไรเมื่อมี breaking change

ถ้าคุณสร้างด้วย workflow สร้างโค้ดอัตโนมัติ (เช่น ใช้ Koder.ai เพื่อ scaffold endpoints และ responses) ให้ยังทำการทดสอบ fake-client โค้ดที่สร้างอาจดูถูกต้องแต่ใช้งานจริงอาจยังไม่ลื่นไหล

ผลลัพธ์คืออีเมล support น้อยลง การปล่อย hotfix น้อยลง และ v1 ที่คุณรักษาได้จริง

การส่ง SDK ขนาดเล็กโดยไม่ทำให้เกินจำเป็น

SDK แรกไม่ใช่ผลิตภัณฑ์ที่สอง คิดว่ามันเป็นตัวห่อบาง ๆ ที่เป็นมิตรรอบ HTTP API ของคุณ ควรทำให้การเรียกทั่วไปง่าย แต่ไม่ควรซ่อนวิธีการทำงานของ API หากใครต้องการฟีเจอร์ที่คุณยังไม่ห่อ พวกเขาควรยังสามารถส่งคำขอดิบได้

เลือกภาษาเดียวเริ่มต้นตามสิ่งที่ลูกค้าคุณใช้จริง สำหรับหลาย API B2B นั่นมักเป็น JavaScript/TypeScript หรือ Python การส่ง SDK หนึ่งตัวที่สมบูรณ์ชนะการส่งสามตัวที่ครึ่ง ๆ

สิ่งที่ SDK ขนาดเล็กควรมี

ชุดเริ่มต้นที่ดีคือ:

• การจัดการ auth (API key หรือ OAuth token) รวมในที่เดียว
• timeout ที่สมเหตุสมผลและการลองใหม่อัตโนมัติสำหรับคำขอที่ปลอดภัย (GET) พร้อม backoff
• ตัวช่วยการแบ่งหน้าให้เป็น iterator หรือฟังก์ชัน next page
• แบบจำลองคำขอ/การตอบกลับที่ชัดเจน (แม้เป็นชนิดพื้นฐาน)
• ช่องทางหนีออกสำหรับ headers ที่กำหนดเองและการเรียก HTTP ดิบ

คุณสามารถเขียนด้วยมือหรือสร้างจาก OpenAPI spec การสร้างโค้ดดีเมื่อสเปกถูกต้องและคุณต้องการ typing ที่สม่ำเสมอ แต่จะสร้างโค้ดจำนวนมาก ในช่วงแรก client เขียนมือเล็ก ๆ บวกไฟล์ OpenAPI สำหรับเอกสารมักเพียงพอ คุณสามารถเปลี่ยนไปใช้ไคลเอนต์ที่สร้างได้ทีหลังโดยไม่ทำให้ผู้ใช้เดือดร้อน ตราบใดที่อินเทอร์เฟซสาธารณะของ SDK คงที่

เวอร์ชัน SDK แยกจาก API

เวอร์ชัน API ควรตามกฎความเข้ากันได้ เวอร์ชัน SDK ควรตามกฎการบรรจุแพ็กเกจ

ถ้าคุณเพิ่มพารามิเตอร์ optional ใหม่หรือ endpoint ใหม่ นั่นมักเป็นการ bump เลขย่อยของ SDK การปล่อย SDK ครั้งใหญ่ให้สงวนไว้สำหรับการเปลี่ยนแปลงที่ทำให้แตก (เช่น เปลี่ยนชื่อเมธอด หรือเปลี่ยนค่าเริ่มต้น) แม้ API จะไม่เปลี่ยน การแยกนี้ช่วยให้อัพเกรดสงบและลดกระทู้ support

ข้อผิดพลาดที่พบบ่อยซึ่งทำให้เกิดปัญหาสนับสนุน

เรื่องส่วนใหญ่ของกระทู้ support ไม่ได้มาจากบั๊ก แต่จากสิ่งที่ไม่คาดคิด การออกแบบ API สาธารณะส่วนใหญ่คือการทำให้มันน่าเบื่อและคาดเดาได้เพื่อให้โค้ดฝั่งไคลเอนต์ทำงานต่อไปเป็นเดือน ๆ

วิธีทำให้เสียความไว้วางใจเร็วที่สุดคือการเปลี่ยนการตอบกลับโดยไม่บอกใคร หากคุณเปลี่ยนชื่อฟิลด์ เปลี่ยนประเภท หรือเริ่มคืนค่า null ในที่ที่เคยคืนค่า มันจะทำให้ลูกค้าพังในแบบที่ตรวจสอบยาก หากคุณจำเป็นต้องเปลี่ยนพฤติกรรมจริง ๆ ให้เวอร์ชัน หรือเพิ่มฟิลด์ใหม่และเก็บของเก่าไว้สักระยะพร้อมแผน sunset ที่ชัดเจน

การแบ่งหน้าก็เป็นอีกข้อบ่อย ปัญหาปรากฏเมื่อ endpoint หนึ่งใช้ page/pageSize อีก endpoint ใช้ offset/limit และอีกหนึ่งใช้ cursors ทั้งหมดมีค่าเริ่มต้นต่างกัน เลือกรูปแบบหนึ่งสำหรับ v1 และใช้ให้ทั่วทั้งระบบ รักษาการเรียงลำดับให้คงที่เช่นกัน เพื่อให้หน้า ถัดไปไม่ข้ามหรือทำซ้ำรายการเมื่อมีเรคคอร์ดใหม่เข้ามา

ข้อผิดพลาดสร้างการตอบกลับมากเมื่อไม่สอดคล้องกัน โหมดล้มเหลวที่พบบ่อยคือบริการหนึ่งคืน { "error":"..." } และอีกบริการคืน { "message":"..." } พร้อม status codes ต่างกันสำหรับปัญหาเดียวกัน ลูกค้าจึงต้องเขียน handler เฉพาะ endpoint มากมาย

นี่คือห้าข้อผิดพลาดที่สร้างอีเมลยาวที่สุด:

• เปลี่ยนฟิลด์เงียบ ๆ (ชื่อ, ประเภท, ความหมาย) โดยไม่มีการ bump เวอร์ชันหรือหน้าต่าง deprecation
• กฎการแบ่งหน้าที่ต่างกันตาม endpoint หรือเปลี่ยนค่าเริ่มต้นเมื่อเวลาผ่านไป
• รูปแบบข้อผิดพลาด, status codes, หรือข้อความ validate ต่างกันข้าม endpoint
• ขาด request IDs ทำให้ทั้งสองฝ่ายหา call ที่ล้มเหลวใน logs ยาก
• rate limits ที่เกิดขึ้นทันที โดยไม่มี headers, ไม่มีคำแนะนำการลองใหม่ที่ชัดเจน และไม่มีตัวอย่าง backoff

นิสัยง่าย ๆ ช่วยได้: ทุก response ควรมี request_id และทุก 429 ควรอธิบายเมื่อให้ลองใหม่

เช็คลิสต์ด่วนและขั้นตอนต่อไป

ก่อนเผยแพร่ ทำรอบสุดท้ายเน้นความสอดคล้อง รายละเอียดเล็ก ๆ ที่ไม่ตรงกันข้าม endpoint, docs, และตัวอย่างเป็นสาเหตุหลักของกระทู้ support

การตรวจสอบด่วนที่จับปัญหาส่วนใหญ่ได้:

• การตั้งชื่อ: คำนามสอดคล้อง ทรัพยากรเป็นพหูพจน์ และการตั้งชื่อฟิลด์เป็นแบบเดียวกัน (เลือกแบบหนึ่งและยึดมัน)
• ตัวอย่าง: ทุก endpoint มีตัวอย่างคำขอและการตอบกลับที่สมจริงรวมการแบ่งหน้า
• ข้อผิดพลาด: รูปแบบ error ชัดเจน รหัสข้อผิดพลาดคงที่ และข้อความช่วยเหลือสำหรับความล้มเหลวยอดนิยม
• ขีดจำกัด: พฤติกรรม rate limit ถูกเอกสารและ response มี headers ที่คาดไว้
• ความปลอดภัย: idempotency สำหรับการลองใหม่บนการสร้าง และการจัดการ timeout ที่คาดเดาได้

หลังปล่อย ดูว่าผู้คนเรียกใช้อะไรจริง ๆ ไม่ใช่สิ่งที่คุณหวังให้พวกเขาใช้ dashboard เล็ก ๆ และการทบทวนรายสัปดาห์ก็พอสำหรับช่วงแรก

สัญญาณที่ควรติดตามเป็นอันดับแรก:

• การพุ่งของ 429 (ใครโดนจำกัดและเพราะอะไร)
• p95 latency ต่อ endpoint (endpoint ช้าอาจซ่อน N+1 queries)
• endpoint และพารามิเตอร์ยอดนิยม (พื้นผิว API จริงของคุณ)
• อัตราข้อผิดพลาดตามรหัสสถานะ (400 vs 401 vs 500)
• timeouts และ retries (ไคลเอนต์อาจวนลูปโดยไม่รู้ตัว)

เก็บ feedback โดยไม่เขียนใหม่ทั้งหมด เพิ่มเส้นทางรายงานปัญหาในเอกสาร และติดแท็กแต่ละรายงานด้วย endpoint, request id, และเวอร์ชันของไคลเอนต์ เมื่อคุณแก้ ให้ชอบการเปลี่ยนแบบ additive: ฟิลด์ใหม่, พารามิเตอร์ optional ใหม่, หรือ endpoint ใหม่ แทนพฤติกรรมที่ทำให้แตก

ขั้นตอนต่อไป: เขียนสเปก API หนึ่งหน้าโดยมีทรัพยากร แผนการเวอร์ชัน กฎการแบ่งหน้า และรูปแบบข้อผิดพลาด จากนั้นสร้างเอกสารและ SDK เริ่มต้นจิ๋วที่ครอบคลุมการยืนยันตัวตนและ 2–3 endpoints แกนหลัก ถ้าต้องการไปเร็วขึ้น คุณสามารถร่างสเปก เอกสาร และ SDK เริ่มต้นจากแผนในแชทด้วยเครื่องมืออย่าง Koder.ai (โหมดวางแผนช่วยแม็ป endpoint และตัวอย่างก่อนสร้างโค้ดได้ดี)