การทำเอกสาร API ด้วย Excel หรือ PDF แล้วแชร์ทางอีเมล เป็นวิธีที่คุ้นเคยกันมาก
เมื่อเกิดปัญหา ก็จะติดต่อผู้รับผิดชอบ แล้วค้นหาอีเมลเก่าเพื่อตรวจสอบว่าเอกสารเวอร์ชันที่ลูกค้ามีอยู่คือเวอร์ชันใด จากนั้นอธิบายสิ่งที่เปลี่ยนไปอีกครั้ง ส่งเอกสารที่แก้ไขแล้ว และคอยตรวจสอบอีกทีว่านำไปใช้ถูกต้องหรือไม่
เราทำกระบวนการนี้ซ้ำ ๆ มากเสียจนเริ่มคิดว่านี่คือ งานที่เดิมทีก็จำเป็นต้องทำอยู่แล้ว
แต่ปัญหาไม่ได้จบแค่เอกสารผิดพลาดเพียงครั้งเดียว
ทุกครั้งที่ API มีการเปลี่ยนแปลง ก็จะมีไฟล์ใหม่ อีเมลใหม่ ข้อยกเว้นแยกตามลูกค้า และความทรงจำของผู้รับผิดชอบสะสมเพิ่มขึ้นทีละอย่าง ตอนแรกอาจเป็นเพียงความไม่สะดวกเล็กน้อย แต่เมื่อเวลาผ่านไป ก็ยิ่งยากที่จะยืนยันว่าเอกสารฉบับใดคือฉบับอ้างอิง และทั้งคนกับเวลาที่ต้องใช้เพื่อแก้ปัญหาก็เพิ่มขึ้นตามไปด้วย
หากลูกค้าพัฒนาตามรูปแบบคำขอของเวอร์ชันก่อนหน้า ก็จะเกิดข้อผิดพลาดในการเชื่อมต่อและงานแก้ซ้ำ หากส่งข้อมูลเรื่องฟิลด์บังคับหรือวิธีการยืนยันตัวตนไม่ตรงกัน กำหนดการพัฒนาก็จะล่าช้า และหากเป็น API ที่เปิดใช้งานจริงอยู่แล้ว ก็อาจลุกลามไปสู่ข้อผิดพลาดของข้อมูลหรือระบบขัดข้องได้
กว่าจะรู้ตัวก็มักเป็นหลังจากเกิดปัญหาไปแล้ว ว่าทีมพัฒนาภายในกับลูกค้ากำลังดูเอกสารคนละฉบับกัน
ตั้งแต่นั้นเป็นต้นมา นักพัฒนาต้องหยุดงานที่กำลังทำอยู่เพื่อตรวจหาสาเหตุ ฝ่ายปฏิบัติการต้องค้นหาเอกสารเก่าและประวัติการส่งมอบ ส่วนลูกค้าต้องกลับไปตรวจสอบอีกครั้งทั้งการติดตั้งใช้งานของตนเองและสเปกที่ได้รับ เอกสารที่ไม่ตรงกันเพียงฉบับเดียวสามารถหยุดงานของหลายคนพร้อมกันได้
ถึงอย่างนั้น ปัญหาส่วนใหญ่ก็ยังถูกแก้กันแบบเงียบ ๆ ผ่านโทรศัพท์ อีเมล และเมสเซนเจอร์
บางคนส่งไฟล์ที่แก้แล้วให้อีกครั้ง บางคนอธิบายสถานการณ์ให้ลูกค้าฟัง และนักพัฒนาก็รีบเพิ่มการจัดการข้อยกเว้น ปัญหาเฉพาะหน้าถูกแก้ได้ก็จริง แต่สาเหตุที่เกิดขึ้น ลูกค้ารายใดได้รับผลกระทบ และควรเปลี่ยนอะไรเพื่อไม่ให้ปัญหาเดิมเกิดซ้ำ กลับไม่เคยถูกเก็บไว้ในองค์กร
เวลาที่ใช้ไปกับกระบวนการนี้ เดิมควรถูกใช้กับการพัฒนาและการปรับปรุงผลิตภัณฑ์
ปัญหาที่ใหญ่กว่านั้นคือ กระบวนการทั้งหมดนี้พึ่งพาประสบการณ์ ความทรงจำ และกล่องอีเมลของผู้รับผิดชอบบางคน หากผู้รับผิดชอบไม่อยู่หรือลาออก องค์กรก็ต้องไล่ค้นบันทึกอีเมลและเมสเซนเจอร์เพื่อกอบกู้งานกลับขึ้นมาใหม่
เอกสาร API ที่ไม่ได้รับการจัดการจะไม่หายไปไหน มันยังคงอยู่ทั้งภายในและภายนอกองค์กร และกลายเป็นหนี้เอกสารที่มองไม่เห็นซึ่งสะสมต่อไป
บางทีเราอาจไม่ได้กำลังแก้ปัญหาอยู่ แต่แค่คุ้นชินกับวิธีรับมือด้วยการใช้เวลาของคนมาปิดช่องทุกครั้งที่ปัญหาเกิดขึ้น
เพราะผมเคยเจอปัญหาเหล่านี้ในการทำงานจริง จึงได้สร้าง SpecBridge ขึ้นมา
SpecBridge ไม่ใช่แค่เครื่องมือสำหรับเขียนเอกสาร API แต่เป็นเครื่องมือสำหรับบริหารจัดการเอกสาร API ที่ใช้ตรวจทานการเปลี่ยนแปลงของเอกสาร และเผยแพร่เฉพาะเวอร์ชันที่ได้รับอนุมัติแล้วให้กับลูกค้าและพาร์ตเนอร์ภายนอก
มันไม่ได้มาแทนที่ Swagger แต่เน้นที่การนำเข้า Swagger/OpenAPI และ Postman Collection แล้วจัดการปัญหาที่เกิดขึ้นในกระบวนการส่งต่อเอกสารไปภายนอก
- เปรียบเทียบความต่างระหว่างฉบับที่เผยแพร่อยู่ปัจจุบันกับฉบับที่แก้ไข
- ตรวจทานและอนุมัติการเปลี่ยนแปลง
- แยกฉบับร่างออกจากฉบับเผยแพร่ที่ลูกค้าเห็น
- จัดการขอบเขตการเปิดเผยเอกสารแยกตามลูกค้า
- ตั้งรหัสผ่านและวันหมดอายุสำหรับลิงก์สาธารณะ
- ให้เอกสารล่าสุดที่ได้รับอนุมัติผ่านลิงก์เดิม
โดยไม่ต้องส่งไฟล์ใหม่ให้ลูกค้าทุกครั้ง คุณสามารถนำเอกสารที่ผ่านการตรวจทานภายในแล้วกลับไปเผยแพร่ที่ลิงก์เดิมได้
นักพัฒนาจึงลดงานซ้ำ ๆ ในการค้นหาและส่งต่อเอกสารอีกครั้งได้ และองค์กรก็สามารถจัดการเอกสาร API ด้วยประวัติการเปลี่ยนแปลงที่ถูกบันทึกไว้และเกณฑ์การเผยแพร่ แทนที่จะพึ่งพาความทรงจำของผู้รับผิดชอบเพียงบางคน
ขณะนี้ผมกำลังมองหาพาร์ตเนอร์ที่จะนำ SpecBridge ไปใช้กับการบริหารเอกสาร API จริง และให้ฟีดแบ็กอย่างตรงไปตรงมา
หากทีมของคุณกำลังจัดการเอกสาร API ด้วย Excel หรือ PDF หรือยังต้องส่งเอกสารให้ลูกค้าใหม่ทุกครั้งที่ API เปลี่ยนแปลง ผมอยากลองเริ่มตรวจสอบร่วมกันตั้งแต่เอกสารที่ใช้อยู่ตอนนี้เพียง 1 ฉบับ
มากกว่าคำชมว่าเราทำฟีเจอร์ได้ดีแค่ไหน ผมอยากได้ความเห็นตรง ๆ เกี่ยวกับสิ่งที่ใช้งานจริงแล้วยังไม่สะดวก ขั้นตอนที่ไม่จำเป็น และฟีเจอร์ที่ยังขาดอยู่
ยังไม่มีความคิดเห็น