การใช้ต้นแบบเป็นข้อกำหนดผลิตภัณฑ์ API

ในฐานะผู้จัดการผลิตภัณฑ์ Developer Experience ที่ SendGrid ฉันได้รับมอบหมายให้ระบุโอกาส คุณลักษณะ และผลิตภัณฑ์ที่เกี่ยวข้องกับ API ของเรา สิ่งหนึ่งที่ฉันกำลังดำเนินการอยู่คือการระบุวิธีการเพื่อให้การสื่อสารแนวคิดผลิตภัณฑ์ของฉันกับ PMs วิศวกร และลูกค้าคนอื่นๆ มีประสิทธิภาพมากขึ้น

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

เพื่อนของเราใน UX ได้แก้ไขปัญหานี้ด้วยเครื่องมืออย่าง Invision ซึ่งมีอินเทอร์เฟซแบบคลิกได้ซึ่งคุณสามารถแตะและใช้งานได้ แทนที่จะเป็นเอกสารหรือโครงร่างที่อธิบายอินเทอร์เฟซ เนื่องจาก API เป็นอินเทอร์เฟซ เราจึงต้องการเครื่องมือที่อนุญาตให้โต้ตอบกับข้อกำหนดตามเวลาจริง แทนที่จะเป็นข้อความอธิบายและ JSON ในเอกสาร

การกำหนดข้อกำหนด

อินเทอร์เฟซที่ทดสอบได้นี้ควรมีลักษณะอย่างไรตามข้อกำหนดของผลิตภัณฑ์ มันจะทำงานอย่างไร? มันมีอยู่หรือไม่?

ขณะที่ฉันกำลังอ่านบทที่ 18 "การสร้างสเปกผลิตภัณฑ์ใหม่" ของ Inspired: How to Build Products Customer Love ของ Marty Cagan ฉันก็ตระหนักว่าฉันต้องการแชร์เครื่องมือที่ฉันใช้อยู่ซึ่งเป็นไปตามข้อกำหนดของ Cagan สำหรับข้อมูลจำเพาะของผลิตภัณฑ์ ส่วนใหญ่ สิ่งที่อยากได้ของเขาสำหรับข้อมูลจำเพาะของผลิตภัณฑ์ และรายการส่วนตัวของฉันเองตามข้อกำหนดของต้นแบบตามข้อกำหนด

ข้อกำหนดของ Cagan*:

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

รายการความปรารถนาของ Cagan*:

• คุณจะต้องเสริมต้นแบบ [กับ]:
  • ตรรกะทางธุรกิจ
  • ข้อกำหนดการเปิดตัว
  • ข้อกำหนดในการส่งมอบแพลตฟอร์ม
  • กรณีการใช้งาน
• ฉันต้องการที่จะสามารถใส่คำอธิบายประกอบต้นแบบ

ข้อกำหนดของฉันสำหรับต้นแบบตามข้อกำหนด:

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

ขอแนะนำ StopLight

เครื่องมือที่ฉันใช้อยู่ซึ่งตอบสนองเกือบทุกอย่างข้างต้นเรียกว่า Stoplight.io เป็นแกนหลักของกลไกเอกสาร API และเว็บพรอกซี ช่วยให้คุณสามารถกำหนด API ของคุณโดยใช้ UI ที่ใช้งานง่าย ซึ่งมีทั้ง Swagger และ RAML ที่ดีที่สุดเบื้องหลังเป็นเอ็นจิ้นข้อมูลจำเพาะพร้อมกับความสามารถในการนำเข้าหรือส่งออกจากรูปแบบใดรูปแบบหนึ่ง

เนื่องจาก StopLight เป็นเครื่องมือจัดทำเอกสาร คุณจึงสามารถกำหนดคำขอ การตอบกลับ ส่วนหัว และคำอธิบายสำหรับปลายทางของคุณได้ ด้วยคุณสมบัติพร็อกซี คุณสามารถเรียก API ของคุณและตรวจสอบว่าการเรียกของคุณตรงกับข้อกำหนดของคุณหรือค้นหาปลายทางของคุณโดยอัตโนมัติเพื่อให้เอกสารส่วนใหญ่ของคุณเขียนโดยอัตโนมัติ

พร็อกซีของ StopLight ยังมีคุณสมบัติที่น่าทึ่งอีกมากมาย:

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

หากคุณเปรียบเทียบการรวมกันของรายการสินค้าที่ต้องการของฉัน ข้อกำหนดคุณสมบัติของ Cagan และรายการสินค้าที่ต้องการของเขากับฟังก์ชันการทำงานที่ StopLight มีให้ คุณจะเห็นว่า StopLight ตอบสนองทุกความต้องการและความปรารถนา:

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

เวิร์กโฟลว์ใน StopLight นั้นเรียบง่ายและ ทุกคน สามารถทำได้ โดยไม่คำนึงถึงความสามารถทางเทคนิคของพวกเขา:

• สร้างโครงการใหม่
• เพิ่มข้อกำหนดโดยคลิกและพิมพ์ข้อมูลเกี่ยวกับปลายทาง พารามิเตอร์ คำขอ และการตอบสนอง
• เพิ่มข้อมูลข้อมูลจำเพาะเกี่ยวกับต้นแบบของคุณในหน้าจอคำจำกัดความ
• หากคุณมีคุณสมบัติเสริม ให้เพิ่มโดยใช้มิดเดิลแวร์
• เปิดการเยาะเย้ย
• คัดลอก/วาง URL สาธารณะสำหรับเซิร์ฟเวอร์จำลอง และแบ่งปันข้อมูลนี้เพื่อรับคำติชม

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

ในฐานะผู้จัดการผลิตภัณฑ์ Developer Experience นั้น StopLight ไม่เพียงแต่ช่วยให้ฉันทำงานได้อย่างมีประสิทธิภาพมากขึ้นเท่านั้น แต่ยังใช้งานง่าย และทำให้ขั้นตอนการเตรียมการส่งมอบในการจัดทำเอกสาร API เป็นเรื่องง่าย เนื่องจากเอกสารเริ่มต้นก่อนขั้นตอนการตรวจสอบความถูกต้องของลูกค้าและมีการอัปเดต ตลอดกระบวนการ มีกรณีการใช้งานและคุณสมบัติอื่นๆ มากมายที่ StopLight มีให้ แต่นี่อาจเป็นกรณีหนึ่งที่ส่งผลกระทบต่องานของฉันมากที่สุด

*ข้อกำหนดและสิ่งที่อยากได้ของ Cagan เป็นคำพูดโดยตรงจาก Inspired: วิธีสร้างผลิตภัณฑ์ที่ลูกค้าชื่นชอบ