จากบทความของ Slack เรื่อง How we design out APIs at Slack
ทำการสรุปแนวทางในการออกแบบ API ของระบบออกมาว่าเป็นอย่างไรบ้าง
เพื่อช่วยทำให้ผู้ใช้งานหรือ developer ใช้งานง่ายขึ้น
อีกทั้งช่วยให้การดูแลรักษา API ง่ายขึ้นด้วย
ซึ่งควรต้องคิดตั้งแต่การออกแบบกันเลยทีเดียว
มิเช่นนั้นแทนที่จะได้ API ที่ดีมีประโยชน์ กลับได้ของที่แย่ ๆ ออกมา
โดยมีแนวทางของการออกแบบดังนี้
1. So one thing and do it well
เมื่อเริ่มต้นออกแบบ API นั้น
อาจจะมีหลาย ๆ ปัญหาให้แก้ไข
ซึ่งอาจจะทำให้เกิดความซับซ้อน และ ยากต่อการทำความเข้าใจ
ดังนั้นแนะนำให้เลือกจาก use case หนึ่งมาทำ
เพื่อให้ focus มากยิ่งขึ้น
2. Make it fast and easy to get started
ต้องทำให้เร็วและง่ายต่อการเริ่มต้นใช้งาน
เป็นสิ่งที่สำคัญมาก ๆ
ถ้าใช้งานยาก เริ่มได้ช้า น่าจะไม่ใช้การสร้างมาเพื่อแก้ไขปัญหา
กลับเป็นการสร้างปัญหามากยิ่งกว่า
โดยจะเริ่มตั้งแต่การใช้งานภายใน
เช่นพนักงานใหม่เข้ามา ให้ลองทำการเปิดและลองใช้งาน API ดูว่า
ใช้งานเป็นอย่างไร เริ่มง่ายไหม เร็วไหม
3. Strive for intuitive consistency
API ต้องความสอดคล้องไปในทิศทางเดียวกันและช่วยให้เข้าใจหรือพอเดาได้ว่า API ทำงานอะไร ใช้งานอย่างไรโดยแทบจะไม่ต้องอ่านเอกสารเลยด้วยซ้ำทั้งจากชื่อของ endpointทั้งจากชื่อของ input parameterทั้งจาก output response
โดยเรื่องของ consistency จะมีอยู่ 3 level คือ
Level 1 :: Consistency with Industry standard
Level 2 :: Consistency with your product
Level 3 :: Consistency with your other API methods
4. Return meaningful errors
อีกเรื่องที่สำคัญมาก ๆ คือ การ return error ที่ดี
มีความหมายชัดเจน ไม่กำกวม
เพื่อให้นักพัฒนาที่ใช้งาน เข้าใจได้ชัดเจนว่า
ปัญหาเกิดจากอะไร
จะได้แก้ไขได้ตรงประเด็นมากยิ่งขึ้น
5. Design for scale and performance
เรื่องการ scale และ performance ที่ดี ก็สำคัญไม่น้อยยก
ตัวอย่างเช่น
- ของการทำ paging กับข้อมูลจำนวนมาก ๆ
- ข้อมูลที่ return กลับไปต้องไม่ซับซ้อนมากนัก หรือ ขนาดไม่ใหญ่จนเกินไป
- เรื่องการทำ rate limit ที่สมเหตุสมผล เพื่อช่วยป้องกันระบบงานให้ยังคงทำงานได้ดี
6. Avoid braking changes
ทุกสิ่งอย่าง ล้วนมีการเปลี่ยนแปลง
ดังนั้นเรื่องของ breaking change จึงสำคัญมาก ๆ
ต้องระวังให้ดี ๆ
จะมีนโยบายอย่างไร
โดยที่ Slack จะมีแนวคิดคือ
อะไรที่มัน work ในเมื่อวาน วันพรุ่งนี้ยังต้อง work อยู่เสมอ
ไม่ใช่แค่ case ปกติเท่านั้น
เรื่องของ case อื่น ๆ หรือพวก exception ต่าง ๆ ก็ต้องระวังไว้ด้วย
การแจ้งเรื่องของการเปลี่ยนแปลงต่าง ๆ
จึงต้องวางแผน และ ประกาศ หรือ ติดต่อสื่อสารให้ชัดเจนเสมอ
อีกทั้งสรุปขั้นตอนการออกแบบ API ไว้ดังนี้
ขั้นตอนที่ 1 เขียน API spce ก่อน
เริ่มจากการตั้งปัญหาที่ต้องการแก้ไขและกำหนด use case ของ API ให้ชัดเจน
จากนั้นเริ่มเขียน API spec
เพื่อทำการอธิบายสิ่งที่จำเป็นสำหรับ API
เพื่อทำให้เข้าใจสิ่งที่จะสร้างอย่างชัดเจน
ประกอบไปด้วย
- Method name
- เป้าหมายของ API
- ตัวอย่างของ request และ response รวมทั้ง error ต่าง ๆ ที่สามารถเกิดขึ้นได้
โดยการทำงานจะเป็นทีม ไม่ใช่ทำงานคนเดียว
ขั้นตอนที่ 2 ทำการ review ภายในกันเอง
เพื่อช่วยให้เราเห็นปัญหาต่าง ๆ จากการออกแบบได้อย่างรวดเร็ว
ทั้งจากภายในทีมและต่างทีม
ทำให้เห็นปัญหาจากกลุ่มคนหลายหลุ่ม หลายมุมมอง
ทั้งการตั้งชื่อ การใช้งาน ความปลอดภัย และ performance
ซึ่งจะช่วยลดปัญหาที่จะไปเกิดหรือเจอเมื่อเราต้องพัฒนา
ขั้นตอนที่ 3 ได้รับ feedback แต่เนิ่น ๆ จาก partner
จะทำการส่ง API spec ไปให้กับ partner
เพื่อให้ review และได้รับ feedback ที่เป็นประโยชน์มาก ๆ
ว่าในมุมมองของ partner นั้น API spec เหล่านี้เป็นอย่างไร
เข้าใจหรือใช้งานง่ายไหม
โดยการทำงานจะเป็นรอบสั้น ๆ ไป
เพื่อให้การออกแบบและพัฒนา API ดีขึ้นอย่างต่อเนื่อง
ขั้นตอนที่ 4 มีการทำ Beta testing
ก่อนที่จะปล่อยให้ใช้งานแบบ public
จะต้องทำ beta testing ก่อน
นั่นคือจะเลือก partner มาใช้งานก่อน (Early access)
เพื่อลองทำการ integrate และใช้งานจริง
เพื่อให้ได้ feedback กลับมาเพื่อแก้ไขและปรับปรุงต่อไปอีก
สุดท้ายแล้ว แนะนำให้ของนำไปใช้และประยุกตืให้เข้ากับ use case และทีม
สิ่งที่สำคัญคือ ให้ความสำคัญกับการออกแบบ
เพราะว่าการออกแบบมีหลากหลายทางเลือก
จากนั้นต้องทำการ review หรือทดลอง
เพื่อให้ได้รับ feedback ที่รวดเร็วและต่อเนื่องจากคนหลากหลายมุมมอง
เพื่อทำมาปรับปรุง
นั่นหมายความว่า เป็นการทำงานที่มีความยืดหยุ่นอย่างมากนั่นเอง